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Preface 


This manual is one of a series designed to instruct and guide you 
in using the SPERRY UNIVAC Information Management System 
(IMS) for Operating System/3 (OS/3). It describes and illustrates 
how to write RPG Il action programs. 


This manual is divided into seven sections and four appendixes. 
The topics discussed are: 


Section 1. Setting the Stage 


Introduces and defines IMS terminology related to action 
programming and discusses how IMS and action programs 
interface. 


Section 2. General Rules for Coding Action Programs 


Discusses special coding considerations in writing action 
programs with particular emphasis on the RPG Il/IMS 
interface areas. 


Section 3. Writing an Action Program 


Presents simple programming examples _ illustrating the 
fundamental properties of action programming - processing 
input messages and generating output messages. 


Section 4. Writing a More Complex Action Program 


Presents more complex programming examples illustrating 
the use of internal subroutines and screen format services in 
action programs. 


Section 5. Special Types of Output Messages 


Describes and provides programming examples of the many 
types of output action programs can generate — namely, 
multiple output, continuous output, Output-for-input queueing, 
and output with message switching. 
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Section 6. Using Screen Format Services to Format 
Messages 


Describes how action programs use screen format services 
to format output messages and receive formatted input. 


Section 7. Action Programming in a Distributed Data 
Processing Environment 


Describes the IMS transaction facility for handling distributed 
data processing with IMS. 


Section 8. Compiling, Linking, and Storing Action Programs 


Explains how to compile, link, and store action programs for 
use during online IMS sessions. 


Section 9. Debugging an Action Program 


Describes how to interpret data provided in a snap dump for 
debugging purposes. 


Appendix A. Using Device Independent Control Expressions 
and Field Control Characters 


Describes the use of device independent control expressions 
and field control characters for formatting messages. 


Appendix B. Generating Edit Tables 


Explains the use of the edit table generator for converting 
unformatted input into fixed formats. 


Appendix C. Summary of IMS Error Codes 


Presents all error codes returned by IMS as a result of 
function requests made by action programs. 


Appendix D. Action Program Coding Restrictions 


Presents IMS restrictions for RPG II coding forms. 
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As one of a series, this manual is designed to guide you in 
programming and using the OS/3_ information management 
system. Depending on your need, you should also refer to the 
current versions of other manuals in the series. Complete manual 
names, their order numbers, and a general description of their 
contents and use are as follows: 


mu §=6Information management system (IMS) concepts and 
facilities, UP-9205 


Describes the basic concepts of IMS and the facilities that 
IMS offers. 


w Information management system (IMS) system support 
functions user guide, UP-8364 


Describes the procedures to generate, initiate, and recover 
an online IMS system. 


= Information management system (IMS) action programming 
in COBOL and basic assembly language (BAL) user guide, 
UP-9207 


Describes how to write action programs in COBOL and BAL, 
with extensive examples. 


= Information management system (IMS) terminal users guide, 
UP-9208 


Describes terminal operating procedures, standard and 
master terminal commands, and_ special purpose IMS 
transaction codes. Also includes UNIQUE command formats 
with brief descriptions. The manual is in easel format for 
ease of use at the terminal. 


= #8 Information management system (IMS) data definition and 
UNIQUE user guide, UP-9209 


Describes how to create defined files for use with UNIQUE 
or your action programs and explains how to use UNIQUE. 
Includes extensive examples of data definitions and UNIQUE 
dialogs. 


m= IMS/DMS interface user guide, UP-8748 


Describes how to access a data base management system 
(DMS) data base from IMS. 
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INTRODUCTION 


1. Setting the Stage 


1.1. INTRODUCING IMS 


The SPERRY UNIVAC Information Management System (IMS) is 
an interactive, transaction-oriented file processing system. It is 
interactive because it carries on a conversation with the terminal 
operator; it is transaction-oriented because for each input 
message, the terminal operator receives a response or output 
message. In this way, operators are constantly informed of the 
results of their inquiries. 


® 1.2. INTERACTING WITH IMS 


Action programs Application programs, called action programs, interact with IMS 
process messages to process input messages from terminals, perform file retrieval 
or updating functions, and create output messages. 


Languages used - You can write action programs in RPG Il, COBOL, or basic 

BAL, COBOL, RPG Il assembly language (BAL). IMS also provides a set of action 
programs called the uniform inquiry update element (UNIQUE) that 
performs file retrieval and updating functions through the use of 
commands from the terimnal. 


Purpose of this manual This manual tells you how to write action programs in RPG ll. 
Action programs are similar to standard RPG Il programs, but 
must follow specific rules because they operate under the control 
of IMS. 


Read IMS concepts and Before you start writing action programs, you must understand 
facilities first how IMS works, and what you (or the IMS administrator) must 
do to make it work. This information is in the IMS concepts and 
facilities manual, UP-9205 (current version). We also assume that 
you know RPG Il. For more information about RPG Il coding, 
@ consult the RPG Ii user guide, UP-8067 (current version). 
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INTRODUCTION 
Prerequisites for Throughout this manual, we assume you've read and understood 
using this manual both UP-9205 and UP-8067. However, as required, we briefly 


define terms and describe concepts that are directly related to 
RPG Il action programming. 
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IMS TERMS 





& 1.3. LET'S DEFINE SOME BASIC IMS TERMS 


Action defined The term action programming comes from the fact that the unit 
of work in IMS is the action. An action begins when an operator 
enters a message at a terminal and ends when a response to 
that message is returned. This is an important point to remember 

What action programs do _— Since the action programs you write are involved primarily with 
this activity - processing input messages, performing file retrieval 
or updating, and creating output messages. 


An action always consists of three activities: 


PROCESSING 





Transaction defined A transaction is one action or a series of actions. 


A simple transaction (Figure 1-1) consists of a single action. 


TRANSACTION CODE 






INPUT MESSAGE { CKACCT 2-412-733 ACCOUNT NUMBER 
A hw 
eer 
transaction 


oO CURRENT ACCOUNT BALANCE = $869.22. 
OUTPUT MESSAGE 


*PROCESSING COMPLETE* 


Figure 1-1. A Simple Transaction. /n this example, one action program processes 
the input messsage and produces an output message - the checking 
account balance for the account specified and a processing complete 
notice. 
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IMS TERMS 
A dialog transaction (Figure 1-2) consists of two or more related @ 
actions. 

TRANSACTION CODE 
INPUT MESSAGE { CUST 35567 CUSTOMER NUMBER 
bd 
: Go AMOUNT DUE = $79.25. 
Example — Dialog ramen mare ENTER PAYMENT AMOUNT $25.33 
transaction 
INPUT MESSAGE 
Go 
oD { NEW BALANCE IS $53.92 
OUTPUT MESSAGE 
*PROCESSING COMPLETE* 

Figure 1-2. A Dialog Transaction. /n this example, two action programs are 
sequenced to produce amount due information, allow data entry, and 
compute a new balance for a specific customer account. 

Transaction codes To begin a transaction, the operator enters a 1- to 8-character 

intate cansachons transaction code. (In single-thread IMS, the transaction code is 1 
to 5 characters.) This code tells IMS the name of the action 
program that will process the input message. 

Transaction code Transaction codes are either the entire input message or a part 


defined of it. Transaction codes are defined to IMS at configuration time. 
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TRANSACTIONS 


1.4. HOW YOU STRUCTURE TRANSACTIONS 


Series of action Sometimes a single action program can process the function 
programs processes required. But more often than not, a series of action programs is 








transaction 7 : 
needed. In either case, we create what we call a transaction 
structure. 
Types of transaction Transaction structure depends on how you terminate action 
termination programs. There are four major types of termination: 
> Normal 
> External succession 
> Delayed internal succession 
> Immediate internal succession 
From here on, we'll call the termination types normal termination, 
external, delayed, and immediate succession. 
Distinction between Using the words termination and succession in the same 
termination and context can be somewhat confusing. In IMS, termination means 
Puronnece that an action program is finished processing. Whether you 
specify normal termination, external, delayed, or immediate 
succession, you are telling IMS that the current action program is 
finished processing and is now terminating. 
Succession means that although the action program is 
terminating, the transaction is not complete. A successor action 
program will continue processing the transaction. 
Transaction complete Normal termination says that the transaction itself is complete. 


No more processing occurs. 


However, external, delayed, or immediate succession tells IMS 
that another action program follows and will resume processing. 


Figures 1-3 through 1-6 illustrate these concepts. 





UP-9206 


TRANSACTIONS 





Normal termination 


External succession 
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ACTION 
PROGRAM 


SPECIFIES 
NORMAL 
TERMINATION 


OUTPUT 
MESSAGE 





Figure 1-3. Normal Termination 


Use normal termination to tell IMS that once your program 
creates an output message, the transaction is complete. When 
you don't specify the type of termination, IMS _ terminates 
normally. The last action program in a transaction always ends 
with normal termination. 


INPUT ACTION OUTPUT 
MESSAGE S| PROGRAM || >| MESSAGE 
(1) (1) (1) 


INPUT ACTION OUTPUT ) 
MESSAGE »; PROGRAM MESSAGE 
(2) (2) (2) 





Figure 1-4. External Succession 


Use external succession to tell IMS that the current action 
program is sending an output message and terminating; however, 
the transaction is not complete. When the terminal operator 
enters a second input message, the action program you named 
as external successor processes the second action, produces an 
output message, and terminates. 
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Delayed succession 
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TRANSACTIONS 


INPUT : ACTION | OUTPUT 
MESSAGE } [41 PROGRAM | MESSAGE 
(1) (1) ’ (1) 


PUT MESSAGE ACTION 
(1) QUEUED AS BROGRAKE 
INPUT MESSAGE 

(2) 


OUTPUT 
MESSAGE 
(2) 





Figure 1-5. Delayed Internal Succession 


Use delayed succession to tell IMS that the current action 
program has processed an input message and produced an 
output message; however, that message isn't going to the 
terminal. Instead, it becomes the input message to the action 
program you named as successor. The successor program 
produces an output message that does go to the terminal and 
terminates. With delayed succession, the second action program 
uses the output message of the predecessor as its input 
message. Even though only one input message and one output 
message are seen at the terminal, internally there are two 
separate actions, each with an input and output message. 


INPUT ACTION ACTION OUTPUT 
MESSAGE PROGRAM PROGRAM MESSAGE 
(1) (1) (2) (1) 





Figure 1-6. Immediate Internal Succession 


UP-9206 


TRANSACTIONS 


immediate succession 


Combining transaction 
structures 
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Use immediate succession to tell IMS that the current action 
program processed an input message but is not producing an 
output message. When it terminates, its successor action 
program immediately takes up where processing left off, 
produces an output message and terminates. In immediate 
succession, there is only one input and one output message. 
Thus, two action programs are processing a single action. 


With these four types of termination or transaction structures 
there is a good deal of flexibility in structuring transactions. 
There are basically no limitations as to how you can combine 
them. For example, you can specify immediate succession, 
delayed succession, external succession, and finally normal 
termination, all in turn (Figure 1-7). 












NOTE: 





Connecting lines represent 
immediate internal, delayed 
internal, or external succession, 
or any combination of them. 


ACTION 


PROGRAM 
3 



















ACTION 
PROGRAM 


ACTION 
PROGRAM 










ACTION 
PROGRAM 
7 








TRANSACTION 
TERMINATION 


PROGRAM 
8 


Figure 1-7. Dynamic Transaction Structure 
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ACTION PROGRAM PROCESSING 


1.5. WRITING REUSABLE ACTION PROGRAMS 


Action programs must be 
serially reusable 


RPG II turns off 
indicators and switches 


Action program must 
reset fields © 


You must write action programs so that they are serially 
reusable. This allows different terminals specifying the same 
transaction code to take turns using the same action programs. 
As long as IMS doesn’t require the main storage space, action 
programs remain there after use and aren't reloaded each time 
they are called. 


RPG fl turns off all indicators and internal switches after each 
action program execution. When the same program is again 
initialized for use, RPG Il sets on only the 1P indicator. 


Since action programs are serially reusable, you must reset all 
fields to their original value before reexecuting the program. For 
example, you must blank or zero out any fields you expect to be 
blank or zero since they may contain values from a previous 
execution. 


1.6. HOW YOUR PROGRAM TALKS TO IMS 


Activation record links 
action program to IMS 


Interface area usage 


More information on 
interface areas 


Layout of the 
activation record 
in main storage 


To communicate with IMS, an action program must link itself to 
IMS. This link is the activation record. The activation record 
handles the control and communication of data between IMS and 
your action program. The activation record can contain up to six 
interface areas as shown in Figure 1-8. 


Whether or not you use all six interface areas depends on the 
needs of your action program. All the interface areas are 
optional. In the case of the program information block, whether 
or not you define it in your action program, RPG Il automatically 
returns values to the status code fields after each |/O request. 
We'll discuss these fields in Section 2. 


Also, in Section 2, we'll discuss when, why, and how you use 
the interface areas. 


Figure 1-8 shows how main storage looks when the action 
program PROGO1 is loaded in a multithread IMS system. The 
layout of the activation record is slightly different in single-thread 
IMS. 
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AC “ION PROGRAM PROCESSING 











MAIN STORAGE 


PROGRAM 
INFORMATION 
BLOCK 


OUTPUT 
MESSAGE 
AREA 


CONTINUITY 
DATA AREA ACTION 


PROGRAM 


WORK. PROGO1 
AREA 


INPUT 
MESSAGE 
AREA 


DEFINED 
RECORD 
AREA 





Figure 1-8. The Activation Record in Main Storage 


Figure 1-9 shows the relationship between an action program 
and its interface areas. @ 


ACTIVATION RECORD 





PROGRAM OUTPUT CONTINUITY 
INFORMATION MESSAGE DATA 
BLOCK AREA AREA 


INPUT DEFINED 
MESSAGE RECORD 
AREA AREA 





Figure 1-9. The Action Program and Its Interface Areas 
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ACTION PROGRAM CODING RULES 


2. General Rules for Coding 
Action Programs 


2.1. CODING ACTION PROGRAMS 


Action programs similar Coding action programs is very similar to standard RPG II coding. 
to normal RPG Il programs However, there are some differences since action programs 
operate under the control of IMS. 


Scope of section In this section, the discussion centers around those coding 
specifications that distinguish an action program from standard 
RPG Il programs. We won't discuss the standard RPG II coding 
practices with which you are already familiar. For more 
information about RPG Il coding, consult the report program 
generator II (RPG Il) user guide, UP-8067 (current version). 


Most differences on A sizeable part of this discussion concerns the file description 

file description form form since the major coding differences for action programs 
concern this form. In addition, differences in coding for other RPG 
forms are covered in this section. Where we don’t point out 
differences in coding, assume that action programs conform to 
the same coding rules as standard RPG Il programs. IMS coding 
restrictions for all coding forms are listed in Appendix D. 


RPG Il form names in our discussion of the various coding forms, we refer to them 
as the control, file description, file extension, calculations, input, 
and output forms. 


2.2. IDENTIFYING AN ACTION PROGRAM 


‘A’ on control form You denote an action program by 

denotes action program placing the letter A in column 74 of the 
control form. It tells the compiler to 
generate a program that interfaces with 
IMS. 





DENOTES 


ACTION 
PROGRAM 





UP-9206 
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ACTION PROGRAM CODING RULES 


Naming the program 


Naming restrictions 


Enter the program name in columns 75 
through 80. This name is assigned to 
your program during compilation. When 
you don't specify a name, RPG I 
automatically assigns RPGOBJ as the 
program name. However, since you will 
undoubtedly have numerous __ action 
programs, you will want to give each a 
unique name. 





Figure 2-1 shows the control form coding. 


INVEATED ALTERNATE SUBROUTINE “ 
PRINT COLLATING ACTION PROGRAM 3 


SEQUENCE ll: “poe ianes 


IDEN TIEICATION 


“ 
Zz 
< 
3 
e 
€ 
° 
; 
7 





Figure 2-1. Coding the Control Form 


The program name must conform to the following .... 






be one to six characters; 


start with an alphabetic character (the remainder may be 
any alphanumeric characters); and 


be left-justified. 
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ACCESSING FILES 


e 2.3. DESCRIBING FILES AND INTERFACE AREAS 


Define files as in Use the file description form to describe the files and the 

normal RPG II programs interface areas your action program is going to use. Describe all 
the files the action program accesses just as you would in a 
standard RPG II program. 


File types you can access Action programs access conventional MIRAM, ISAM, DAM, and 
SAM files as well as IMS defined files. (You can access IRAM 
files but you must define them to the IMS configurator as MIRAM 
files.) Conventional files are data files you create via OS/3 data 
management. Defined files are files created by IMS _ from 
conventional files according to user-supplied definitions. For more 
information on creating and using defined files, consult the IMS 
data definition and UNIQUE user guide, UP-9209 (current 


version). 
Where data files are You identify data files used by an action program in the ACTION 
defined to IMS section of the IMS configuration and define each of your 


conventional files in a FILE section. Table 2-1 summarizes the file 
organization, access modes, and file types used in action 
programs. See Appendix D for allowable file description form 


@ entries. 


Table 2-1. Summary of File Types Used by Action Programs 


File organizations, access 
modes, and file types 
used by action programs 


Indexed Random Input/Update/Output* 
Sequential Input 
_ Indexed Random Input/Update/Output* 
| Sequential Input 


Nonindexed Random Input/Update/Output 
(Relative) 


Sequential Input 





Dedicated Sequential 
Sequential 


Indexed Random Input/Update/Output* 





Sequential Input 


Nonindexed Random Input/Update/Output 
(Relative) 

Sequential Sequential Output 

(Disk or Tape) 


“For output files, only ADD is allowed. 








UP-9206 


Where data files are 
defined to RPG I 


Accessing files in 
random mode 


Restrictions on file 
updating 


Accessing files in 
sequential mode 


Writing to sequential 
files 


Where the differences are 
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ACCESSING FILES 


You define all files used by action programs on the file 
description form and input/output form. 


An action program can access ISAM, DAM, MIRAM, and defined 
files in random mode by defining them as chained files on the file 
description form (column 16). 


Operating under IMS, the action program retrieves one record at 
a time. Updating or deleting of the retrieved record must be done 
before the next record is retrieved. Records being added to, or 
deleted from, a file on which updating is being performed cannot 
be added or deleted between the reading and writing of a record 
that is being updated. The ADD or DEL specification in columns 
16-18 of the output form performs add or delete functions. 


An action program can also read ISAM, MIRAM, and defined files 
in sequential mode. Define them as primary or secondary files 
and use normal cycle input, or as demand files and use the READ 
operation on the calculations form. 


An action program can write output to a SAM file or dedicated 
sequential MIRAM file. Sequential input files (disk or tape) are not 
supported. However, you can read a disk MIRAM file sequentially 
by defining it as a random file (MODE=RAN) in the FILE section 
of the IMS configuration. 


The major difference in coding the file description form is the use 
of the interface areas or activation record. The interface areas 
and how you code them are described in 2.4 through 2.19. 

















UP-9206 SPERRY UNIVAC OS/3 2-5 
IMS ACTION PROGRAMMING IN RPG li 


INTERFACE AREAS 


e 2.4. DEFINING THE INTERFACE AREAS 


Activation record The activation record handles the control and communication of 
data between IMS and your action program. The activation 
record can contain as many as six interface areas: 


Interface area names 





Input message area (IMA) Continuity data area (CDA) 


Output message area (OMA) Work area (WA) 


Program information block (PIB) Defined record area (DRA) 





On the file description form, define the interface areas your action 
program intends to reference. You never define a work area or a 
defined record area, although these areas may be part of your 
program's activation record. 


Sample coding of interface Notice in Figure 2-2 that the action program PROGO1 has defined 
@ areas one data file, CUSTFIL, and four interface areas. This means that 
PROGO1 intends to reference the input message area, output 
message area, program information block, and continuity data 
area during processing. 


FILE PROCESSING MODE EXTENSION OR 
FILE OESIGNATION KEY OF RECORD LINE COUNTER 
ADORESS FIELD LENGTH 
RECORD AODRESS TYPE 
FILE FORMAT FILE ORGANIZATION 
OVERFLOW 
© invicator 
a.ocx | Aecoro 
vencTa | LENGTH 


PISPRIC/DIT 
FIVID 


Example 





LeBBoS BE 
ayia TT 





Figure 2—2. Defining Files and Interface Areas 
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INTERFACE AREAS 


Assigning interface area 
file names 


Acceptable entries 
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The interface areas are defined just like 
any other file. You assign a unique file 
name in columns 7-13 for each interface 
area. This file name follows the standard 
rules for file names. The file name you 
assign can be the same as the interface 
area name. 


Table 2-2 summarizes the entries you 
must make. 





Table 2-2. Coding Interface Areas on the File Description Form. When you define 
an interface area, you must make these entries on the file description 
form. 








ES 


16 + message | *IMA 
size 


U, 0 D, blank F 16 + message 
size 
LU F Varies 
(70 maximum) 
size 
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PROGRAM INFORMATION BLOCK 


2.5. DEFINING THE PROGRAM INFORMATION BLOCK (PIB) 


Purpose The program information block passes control data between IMS 
and the action program after 1/O and at termination. It is a 
Size predefined 145-character area. Your action program can access 


only the first 70 characters. The remaining 75 characters are for 
IMS internal use only. 


RPG II checks status The program information block is always present in the activation 

codes record, but you don’t need to define it unless you reference it. 
After each !/O request, RPG Ii automatically checks the status 
codes and makes them available whether or not you define the 
program information block. 


Define PIB as input demand You define the program information block in one of two ways: 
or update demand file 
> as an input demand file; or 


> as an update demand file 


Type depends on use Choose input demand if you intend only to read it for data. If you 
intend to update it, you must define it as an update demand file. 


UP-9206 
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PROGRAM INFORMATION BLOCK FIELDS 


Summary of program 
information block fields 




























12 


13-20 


21-27 


28-34 


35-36 


37-38 


39-40 


41-42 


43-44 


13-14 


15-16 


17-20 





2-8 


Structure of the Program Information Block 


Before discussing the program information block, let's take a 
look at the data it contains. Table 2-3 summarizes the contents 
of the program information block; subsection 2.6 is a detailed 
description of the fields action programs can reference. 


Table 2-3. Contents of the Program Information Block 


SSS 
Status-code 


Detailed-status-code 
Successor-id 
Termination-indicator 
Lock-rollback -indicator 
Transaction-id 

Year 

Day 

Time 

Data-def-rec-name 
Defined-file-name 
Standard-msg-line-length 
Standard-msg-number-lines 
Work-area-length 
Continuity-data-input-length 
Continuity-data-output-length 


Work-area-inc 





Continuity-data-area-inc 


Success-unit-id 


Transaction-date 


Year 

Month 

Day 

Time of day 

Hour 

Minute 

Second 

Filler 

Source-terminal-chars 
Source-terminal-type 
Source-term-msg-line-length 
Source-term-msg-number-lines 
Source-term-attributes 


DDP-mode 


























UP-9206 SPERRY UNIVAC OS/3 2-9 
IMS ACTION PROGRAMMING IN RPG II 





STATUS CODES 





2.6. HOW PROGRAM INFORMATION BLOCK FIELDS ARE USED 





Status-code Status-code (positions 1-2) is a half-word binary integer value 
returned by IMS indicating the completion status of a request. 
Remember that RPG Il still sets *ERROR to indicate the error 
condition; however, the status code provides more detailed 
information. The status-code values are: 


Status-code values 


Successful 

Invalid key or record number 

End of file or unallocated optional file 
Invalid request 

1/0 error 

Violation of data definition 

Internal message control error 


Screen format error 








When status-code=3 An invalid request status code is returned when IMS detects an 

(invalid request) error in a request before passing the request to data 
management, the control system, or the integrated 
communications access method (ICAM). 


When status-code=4 IMS returns an I/O error status code when an unrecoverable error 
(1/0 error) is detected by data management, the control system, or ICAM. 

When you configure You specify an error return option for each action program at 
ERET—YES configuration time. If you choose to accept errors (ERET=YES 


specified to the configurator), then, regardless of the status-code 
value, the action program regains control when the request is 
completed. When an error occurs, *ERROR is set. If you want 
more information about the error, you must test for the various 
status codes. 


When you don’t configure \f the option to reject errors is chosen or defaulted at 

ERET—YES configuration time, IMS returns control to the action program only 
when the status code equals O,1,or 2. When any other status 
code is returned, the action program doesn't regain control. 


UP-9206 


STATUS CODES 


Recommendation 


Detailed-status-code 


Detailed-status-code 
for I/O error 


Detailed status codes 
for other errors 
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We strongly advise that you specify ERET=YES so that your 
program can regain control and terminate orderly. 


Detailed-status-code (positions 3-4) is a half-word binary value 
returned by IMS following a request when the status code is 
invalid request (3), I/O error (4), internal message control (6) 
error, or screen format (7) error. The detailed status code 
provides more detailed information concerning the error. IMS also 
returns detailed status codes for invalid key (status code 1) when 
you use defined files. 


When the status code is |/O error (4), the detailed status code 
contains either filenameC + 2 or the error code and subcode 
returned by the file access method. All file types except MIRAM 
return a detailed status code of filenameC + 2. MIRAM files return 
an error code (DM) and subcode. You can find these messages in 
the system messages programmer/operator reference, UP-8076 
(current version). 


The detailed status codes for status codes 1, 3, 6 and 7 are 
listed in Appendix C. 
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PROGRAM SUCCESSION AND TERMINATION 





Successor-id Successor-id identifies the action program that takes control 

(positions 5-10) when the current program terminates. You must move the name 
of the successor action program into successor-id whenever you 
terminate with external, delayed, or immediate succession. 

Size and name Successor-id is a 6-character field. The name you assign must be 
left-justified and zero-filled. 


When you specify normal When the action program uses normal termination, don't specify 
termination a value for successor-id. 


Use to find cause of errors The successor-id field is also used to find and display the cause 
of errors. To find the cause of an error, check the status-code 
field, associate a successor-id with each possible error condition, 
and assign an error code to each condition. When an error 
occurs, move the error code to the successor-id field and 
terminate your action program abnormally by moving A or S to 
the termination-indicator field. IMS sends the error code from the 
successor-id field to the terminal after abnormal termination. 





Termination-indicator Termination-indicator is a 1-character value that shows the type 

tposiion 17] of termination for the current program. (See 1.4 for a description 
of the types of termination.) You select the type of termination 
by moving a specific character to the termination-indicator field. 


Default value When you don't move a value to termination-indicator, IMS 
assumes normal termination. 


Table 2-4 lists the character, type of termination it selects, and 
IMS operations that take place. 
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PROGRAM SUCCESSION AND TERMINATION 


Table 2-4. Termination Indicators 


Termination types and 
IMS operations 


SS 


Normal Output message is sent to terminal. 
Termination All resources, including current action 
program, are released. When 
you don't move a value to this 
field, normal termination is assumed. 


External Output message is sent to terminal. 
Succession Any data saved by this program is stored 
in the continuity data file. 
All resources, including current action 
program, are released. Successor action 
program is scheduled when another 
input message is received from 
originating terminal. 


Delayed No output message goes to the terminal. 
Succession Output message is queued as input message 

to. successor action program. Any 

data saved by the program is stored in 

the continuity data file. All 

resources, including current action 

program are released. Successor 

action program is initiated by 

normal scheduling process. 


Immediate No output message goes to the terminal. 
Succession Current action program only is released. 
Successor action program is immediately 
initiated and IMS passes to it (intact) 
the interface areas of the predecessor 
program. 


Abnormally Sends error message to originating 

without terminal {includes value moved to 

Snap Dump successor-id). All resources are released. 
All files are rolled back. 


Abnormally Same as A except a snap dump of current 

with Snap action program and its activation record 

Dump is also provided. To get a snap dump, specify 
// OPTION DUMP, JOBDUMP, or SYSDUMP 
in your IMS job control stream. 





Table 2-5 summarizes the types of termination an action 
program can specify and the associated successor-id entries. 
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Table 2-5. Summary of Action Program Termination Types 
and Successor-ids 


Successor-id Ignored Termination Termination code Successor Successor Successor 
code program name program name program name 


Termination- S E D 
Indicator 





Involuntary termination The termination-indicator field controls voluntary termination of 
action programs. Action programs can_ also _ terminate 
involuntarily. Involuntary termination occurs when IMS encounters 
an abnormal condition in the processing of a request issued by 
an action program. Involuntary termination occurs when action 


Causes program execution causes a program check or when an execution 
loop within an action program continues beyond a specified time 
Result limit. When any of these conditions occurs, IMS sends a 3-line 


message to the originating terminal and to the system console, 
giving the cause of the abnormal termination. Abnormal 
termination messages are listed in the system messages 
programmer/operator reference, UP-8076 (current version). 


Obtaining a dump A snap dump of the action program and its activation record is 
performed only when // OPTION DUMP, JOBDUMP, or 
SYSDUMP is specified in the job control stream for executing 
IMS. 
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LOCK ROLLBACK 


Lock-rollback-indicator 
(position 12) 


Default value 


Holding of locks 
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Lock-rollback-indicator is a 1-character value, set by the action 
program, that indicates the record lock and rollback functions you 
want performed at action program termination. Table 2-6 
summarizes the possible entries for this field. 


Table 2-6. Summary of Record Locks and Rollback 





Holds all locks imposed by the current action program 
into the successor program. 










Releases all pending locks set by the current action 
program. Update locks are held into the successor 
program. 














Releases all locks for the transaction. Establishes a 
new rollback point in the audit file. This is the default 
value. 










Releases all locks for the action or transaction. Rolls 
back all updates for this action or transaction. 
Establishes new rollback point in the audit file. 


IMS checks the lock-rollback-indicator field at action termination 
for external and delayed succession or normal termination. When 
you don’t specify a value in lock-rollback-indicator, IMS assumes 
the value N. Don’t confuse this with the N_ signifying normal 
termination. 


IMS doesn't check the lock rollback indicator when you terminate 
with immediate succession. All records remain locked since there 
is only one action taking place in immediate succession and IMS 
always holds locks for at least the length of the action. 
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Caution in using RandH Use the R and H options only when the termination indicator is 

options set to E for external succession or D for delayed succession. In 
long transactions, use R and H with caution. Holding of locks 
across action programs in a multithread environment can cause 
deadlock. In a single-thread environment, holding locks across 

Single-thread restriction actions can decrease response time. In single-thread IMS, you 
can use the R and H _ indicators only when you _ specify 
RECLOCK=YES in the OPTIONS section of the configuration. See 
the IMS system support functions user guide, UP-8364 (current 
version). 


Advantages of the N option Use the N option for long-running update transactions. The N 
option releases all locks when the termination indicator is set to 
E for external succession or D for delayed succession. With 
normal termination, locks are always released and a new rollback 
point is established. This option also establishes additional 
rollback points, limits the range of rollback, and reduces the size 
of the audit file. The audit file contains the before-image of 
records to be updated. By limiting the number of updates in an 
action program or by establishing additional rollback points in a 
long-running transaction, you reduce the size of the audit file and 
save disk space. 


@ Getting online file recovery The O option activates online file recovery to roll back files to 
the previous rollback point. Use the O option for external and 
delayed succession or normal termination. 


Lock for update If you specify lock for update (LOCK=UP) for a particular file in 
the FILE section at configuration time, IMS releases record locks 
when updates are completed rather than at the end of an action. 
When you use this option, IMS doesn’t save before-images in 
the audit file and doesn’t roll back updates at abnormal 
termination. You can use the R indicator to release locks on 
uncompleted updates at the end of an action, or the H indicator 
to hold locks on uncompleted updates into the next action. 
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Transaction-id 
(positions 13-20) 


Data-def-rec-name 
and defined-file-name 
(positions 21-34) 


IMS places configured 
values in these fields 


Passing new names to 
successor program 


Using conventional files 
in successor program 


Standard-msg-line-length 


(positions 35-36) 
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Transaction-id is a unique identification for a transaction. IMS 
sets this value for ail action programs that are part of the same 
transaction. The first part is the date in Julian form; the second 
part is a unique number assigned by IMS. If you require the 
accurate date and time in your action program, use_ the 
transaction-date and time-of-day under success-unit-id. 





If your action programs access a_ defined file, the 
data-def-rec-name (positions 21-27) and _ defined-file-name 
(positions 28-34) fields name the defined file or subfile. Both are 
7-character items, left-justified and blank filled. The description of 
the defined file is contained in the data definition record in the 
NAMEREC file. 


When IMS schedules the first action in a transaction, it places: 


m the data definition record specified by the DDRECORD 
configurator parameter into the data-def-rec-name field; and 


m the defined file name specified by the DFILE configurator 
parameter into the defined-file-name field. 


When your action program terminates in external or delayed 
succession and the successor program accesses a different 
defined file, you can pass the new data definition record name 
and defined file name to the succeeding program either by: 


1. placing the new names_ in data-def-rec-name and 
defined-file-name; or 


2. placing zeros in both fields and allowing IMS to insert the 
values configured for the successor action. 


If the successor program accesses only conventional files, your 
action program should place zeros in data-def-rec-name and 
defined-file-name. This allows the successor program to access a 
conventional file that may have contributed to the defined file 
used in the previous action. 





Standard-msg-line-length is a half-word binary integer that shows 
the maximum line length for a message. IMS obtains this value 
from the CHRS/LIN configurator parameter. 

















UP-9206 SPERRY UNIVAC OS/3 2-17 
IMS ACTION PROGRAMMING IN RPG II 


OTHER PROGRAM INFORMATION BLOCK FIELDS 


@ Standard-msg-number-lines_ Standard-msg-number-lines is a _ half-word binary integer that 
(positions 37-38) shows the maximum number of lines for a message. IMS obtains 
this value from the LNS/MSG configurator parameter. 





Work-area-length Work-area-length is a half-word binary integer. It contains the 

(positions 39-40) size of the work area specified at configuration time. You must 
configure a work area when your action program uses screen 
format services. RPG Il uses this work area to store the variable 
output fields while the screen is built. This all happens internally. 
The action program itself doesn't use the work area. 


Continuity-data-input-length Continuity-data-input-length is a half-word binary integer. It 
(positions 41-42) contains the size of the continuity data record passed by the 
predecessor program. 


Continuity-data-output- Continuity-data-output-length is a half-word binary integer that 

length defines to the current action program the configured size of the 

(penone aa ae) continuity data area. When the current program terminates, this 
field contains the size of the continuity data area passed to the 
successor program. 


@ Work-area-inc Work-area-inc is a half-word binary integer. Move a value to this 
(positions 45-46) field when you need to increase the size of the configured work 
area in the successor action program. You do this because you 
know the configured size will not be large enough to hold the 
screen that the successor program wants screen format services 
to build. 


Continuity-data-area-inc Continuity-data-area-inc is a half-word binary integer. Move a 

(positions 47-48) value to this field when you want to increase the configured size 
of the continuity data area for the successor action program. IMS 
adds this increment value to the length of the continuity data 
record that the current action program is saving. It then 
compares this value to the configured continuity data area size. 
The larger value becomes the size of the continuity data area for 
the successor action program. 





Success-unit-id Success-unit-id provides a calendar date and clock time for your 

{positions 49-63) action program at the beginning of each success unit. Reference 
this field when your action program requires an accurate 
date/time value. 
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Source-terminal-type 
(position 64) 


Source-term-msg-line- 
length 
(positions 65-66) 


Source-term-msg-number- 
lines 
(positions 67-68) 


Source-term-attributes 
(position 69) 





Source-terminal-type is a 1-character field containing a type code 
for the source terminal. The values set by IMS are: 


System console 

UTS 400 terminal in native mode (with or without character-protect feature) 
UTS 10, DCT 500, DCT 1000, or teletypewriter 

UTS 400 terminal in UNISCOPE mode with FCC-protect feature 

UTS 400 text editor 

UTS 400 terminal in UNISCOPE mode with character-protect feature 
UNISCOPE 100 or UNISCOPE 200 terminal 

Workstation or UTS 20 terminal 

IBM 3270 terminal 


UTS 40 terminal 





Source-term-msg-line-length is a half-word binary integer that 
specifies the number of characters per line for the source 
terminal. For hard copy terminals, this is the configured line 
length (CHRS/LIN specification in the GENERAL section of the 
IMS configuration). 


Source-term-msg-number-lines is a half-word binary integer that 
specifies the number of lines for the source terminal. For hard 
copy terminals, this is the configured number of lines (LNS/MSG 
specification in the GENERAL section of the IMS configuration). 


Source-term-attributes is a 1-character field defining specific 
attributes of the source terminal. The values it can contain are: 





Screen bypass and Katakana 
Katakana character set 
Nonvideo device 

Screen bypass feature 


None of these attributes 
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DDP-mode (position 70) DDP-mode is a 1-character field that identifies the type of remote 


transaction in distributed data processing. The values set by IMS 
are: 








Transaction was initiated because of an ACTIVATE request from an action 
program (program-initiated transaction). 






Transaction was initiated by directory or operator routing (operator-initiated 
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2.7. HOW TO READ THE PROGRAM INFORMATION BLOCK 


Defining PIB as an 
input demand file 


Using status codes to 
determine processing 


Sample file description 
form coding 


Column 19 
(file format) 


Omit block length 


Columns 24-27 
(record length) 
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2-20 





To read the PIB (but not update it), define it as an input demand 


file on the file description form. 


Let's assume that in your action program you want to be able to 
read the status-code and detailed-status-code fields, and based 
on the values they contain, determine what processing is done. 


Figure 2-3 shows the file specifications. 


FILE PROCESSING MODE 
FILE DESIGNATION KEY OR RECORD 
AODRESS FIELO LENGTH 


RECORO ADDRESS TYPE 
FILE FORMAT FILE ORGANIZATION 


> OVERFLOW 


INDICATOR 
eLocK RECORD 


PISIRICIOIT 


IF] 
i 





TARTING | 2 


LENGTH | LENGTH =16 KEY FIELD 
= ‘ s 


Locarion |” 
38] 39]40 





EXTENSION 


DITION/UNOROERED LOAO 


DER OVERFLOW 
PERCENTAGE X10) 


NUMBER OF EXTENTS 








Figure 2-3. Defining the Program Information Block as an Input 


Demand File 


First, name the file. In Figure 2-3, the 
file name is PIB. Then, enter an 1 in 
column 15 for file type and a D in 
column 16 for file designation. 


Enter an F in column 19 for file format. 
For RPG Il action programs, the file 
format entry is always F. 


Omit block length (columns 20-23). If 
you enter a value, it must equal record 
length. 


Enter 4 since  status-code and 
detailed-status-code are the first four 
characters of the program information 
block. These are the fields you want to 
read. If you choose, you can reference 


all 70 characters of the program information block by entering 70 
for record length. By doing that, you can read any of its fields 


during your action program. 
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Considerations in In defining record length, specify at least -the number of 
determining record length ~~ characters up to and including the field or fields in the program 
information block that you want to read. 


Columns 40-46 Specify *PIB. You may not enter any 
{device name} other name. 
Input form entries To get the values for status-code and 


detailed- status-code into your action 
program, you have to name these fields 
on the input form (Figure 2-4). You can 
assign any name you choose, provided 
the position you assign to them 
corresponds exactly to their position in the program information 
block. Program information block fields defined on the input form 
that are not read by your action program are flagged at 
compilation as unreferenced. 





@ AECORD IDENTIFICATION CODES 


POSITION 


POSITION 


ures 
CHAINING FIELOS 


N:NOT 
R czo 
CHARACTER 
CHARACTER 
MATCHING FIELOS OR 
FIELD RECORD 
RELATION 


N-NOT 
2D 
B CONTROL LEVEL 


re 
& 











INDICATORS 


ITHMETIC 


BS 
gf 





H 8 
oe sl 








Figure 2-4. Testing Status and Detailed Status Codes 


Specify binary In column 43 of the input form, specify 
fields B, because status-code and detailed- 
status-code are binary fields. 
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READING THE PROGRAM INFORMATION BLOCK 


Specifying the READ 
operation 


Testing for 
status codes 


No end-of-file indicator 
set on 
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In columns 47 and 51, specify the 
starting and ending positions. 





On the calculation form, specify the READ operation for the file 
name you assigned to the program information block. 


To test the status codes and detailed status codes, specify the 
COMP operation for the field names you specify on the input 
form. Figure 2~4 shows the coding to test for a status code of 3 
and detailed status code of 6. 


You may read the program information block as many times as 
you want. RPG Il doesn’t set on the end-of-file indicator. 
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2.8. HOW TO UPDATE THE PROGRAM INFORMATION BLOCK 


Defining PIB as an To update the program information block, define it as an update 

update demand file demand file. There are many instances when you will need to do 
this. The most common reason for updating the program 
information block is to specify types of termination - normal 
termination, external, delayed, or immediate succession. 


Updating successor-id and Let's assume your transaction contains two action programs, 

termination-indicator PROGO1 and PROGO2. For processing to continue when PROGO1 
terminates, PROGO1 must name its successor and the type of 
termination. PROGO1 does this by updating the program 
information block. On the output form, it moves the name of the 
successor program, PROGO2, into the successor-id field and 
moves the termination code, E, D, or |, depending on the type of 
termination desired, to the termination-indicator field. Now let's 
take a look at how you code the file description form to allow 
for this updating. 


Sample file description In Figure 2-5, you see how we defined 

form coding the program information block as an 
update/demand file in columns 15 and 
16, and entered an F for file format in 

Defining record length column 19. For record length, we 
specified 11 since termination-indicator 
occupies position 11 in the program 
information block. You must specify at 
least 11 character positions when 
updating the termination-indicator field. 


Device name Enter *PIB in columns 40-46. You can’t 
substitute any other name in these 
columns. 





FILE TYPE FILE PROCESSING MOUE EXTENSION OR RDERED LOAD 
FILE OESIGNATION KEY O8 RECORD LINE COUNTER 
ENO OF FILE ADORESS FIELO LENGTH cope 
SEQUENCE RECORD ADDRESS TYPE 
FILE FORMAT FILE ORGANIZATION 
> OVERFLOW 
© inocator 
of aocK RECORD x 
3) GENGTH | LENGTH | -{9 KEY FIELO 


o|> oa 
2/2 x TARTING 
ehul at] u 4 SrA Ne 


3/2 
3/3 
rl 
3|s 


LocarTion | ~ 
7 13}14]15 116 f17/ 18 {19} 20, 23424 27{28|29 30] 31]32]33 34]35 38] 29440 





un FIP. T.B, | FE faba 4 4 ares 











Figure 2-5. Defining the Program Information Block as an Update 
Demand File 
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Sample output form coding The actual updating of these fields 


No READ operation 








occurs at output. Figure 2-6 shows the 
output form for PROGO1. The file name 
is PIB. It matches the name assigned to 
the program information block on the 
file description form. We defined the 
end positions for output as 10 and 11, 
respectively. Position 10 is the end 
position for successor-id; and 11, for 
termination-indicator. In columns 45-70, 
we indicated ‘PROGO2’ as the name of 
the successor program and ‘I’ for 
immediate succession as the type of 
termination. When PROGO1 terminates, 
‘PROGO2’ is moved to the successor-id 
field and ‘I’ to termination-indicator. IMS 
then checks the fields to determine what 
processing takes place next. 








OUTPUT INOICATO 
DATA FORMAT 
PrBsLIR 


END 
POSITION 
IN 
output 


IDENTIFICATION 


RECORD 


® 8 BLANK AFTER 














Figure 2-6. Designating a Successor Program and Type of 
Termination 


You don't need to read the program information block before 
updating it. RPG Il does this for you. However, you must define it 
as an update demand file. 


You define it as an update demand file so you can change 
individual fields. If you define it as an output file, you must supply 
all fields or the information contained in the fields you don't 
supply will be overlaid by blanks. Therefore, it is much easier to 
define it as an update demand file. 


When you specify the PIB as update demand and do not supply 
input specifications, you receive a warning message that there 
are no input specifications. This is only a warning message and 
you need not take any action. 


When reading the program information block, be aware that the 
end-of-file indicator is not set on by RPG Il. 
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2.9. DEFINING THE INPUT MESSAGE AREA (IMA) 


The input message sent from the terminal goes to the input 
message area where it awaits processing by the action program. 
You define an input message area if your action program 
references it. 


Defining the input Generally, the IMA is defined as a primary input file since the 
meseage.area input message coming in from the terminal often contains data to 
be processed by the action program. 


Size The input message area’s size is usually specified at configuration 
time. When the size isn’t specified or the size specified is 
inadequate, IMS allocates an area large enough to handle the 
entire input message. 


Control header In addition to the input message coming in from the terminal, the 
input message area also contains a control header. The control 
header is 16 characters long and contains data generated by IMS 
related to the input message. 


Format of the Input Message Area Header 


Table 2-7 lists the fields that comprise the input message area 
control header. 


Summary of header fields Table 2-7. Input Message Area Control Header Contents 















Source-terminal-id 


5-12 Date-time-stamp 

13-14 Text-length 

15 Reserved for system use 
16 Auxiliary-device-id 


ade Device = Aux1 
C2’ Device = Aux2 
C3’ Device = Aux3 
c'4' Device = Aux4 
c's’ Device = Aux5 
c's’ Device = Aux6 
C'7' Device = Aux7 
Cc’'38’ Device = Aux8 


c's’ Device Aux9 
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INPUT MESSAGE AREA 


Source-terminal-id 
(positions 1-4) 


Message-identifier 
(positions 5-12) 


Text-length 
(positions 13-14) 


Auxiliary-device-id 
(position 16) 
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The input message area control header contains the following 
items: 





Source-terminal-id identifies the terminal that sent the input 
message. 





Message-identifier is a unique identifier for each input message. 
The first part is the date; the second part is a unique number 
assigned by IMS. It is given in binary integers. 





Text-length is a binary half-word integer that specifies the length 
of the input message text. 





Auxiliary-device-id is the configured number of the auxiliary 
device transmitting data to the action program. This number is 
specified in the communications network definition. 
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e 2.10. READING THE INPUT MESSAGE AREA 


Defining IMA as In most circumstances, the input message area is defined as a 

an input file primary input file since the input message sent from the terminal 
is the first data you want the action program to process. 
Consequently, as soon as your action program begins 
processing, RPG Il reads the input message area. Study Figure 
2-7 for a moment. 


Sample file description In Figure 2-7, we define the input 

form coding message area as INMSG in columns 
7-13, file name. You must give the 
input message area a unique name; you 
can name it IMA. 


Columns 15,16,24-27 We entered IP for primary input in 
columns 15 and 16, respectively. The 
record length entry is 48. This 
designates the size of the input message 
(32 characters plus an additional 16 
characters for the IMA control header) 
that this action program is expecting. 





@ Device name The entry *IMA in columns 40-46 is 
required. You may not substitute any 
other name. 

Read once only RPG Il reads the input message area 


only once. After this, any attempt to 
read this area sets the  end-of-file 
indicator on. 


EXTENSION OR 
FILE DESIGNATION. KEY OR RECORD LINE COUNTER, 
ADDRESS FIELD LENGTH coor 
RECOAO ADORESS TYPE 
FILE FORMAT 
OVERFLOW 
tNDICATOR 
RECORD 
LENGTH 


& 
= 
~ 
€ 
a 
e 














Figure 2-7. Defining the Input Message Area as a Primary Input File 
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2.11. USING THE INPUT MESSAGE AREA TO PASS DATA 


Defining IMA as an 
update file 


Saving data in the input 
message area 


How to pass data 


Successor program using 
saved data 


Restrictions on reading 
input message area 
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Define the input message area as an update file (Figure 2-8) 
when you want to use it to pass data from the current action 
program to its successor program. 


Normally, you pass data by means of 
the continuity data area. However, when 
you use immediate succession, you can 
pass data to the successor program in 
the input message area. 





To use the input message area to pass data, define it as an 
update file. Then, at termination, output to the input message 
area any data you want to save and pass to the successor 
program. You would code this operation on the output form as 
you would to do output to any file. 


The successor program defines the input message area as an 
input or update file depending on how it intends to use the data. 
To read the data, define it as an input file. To read and update 
the input message area, define it as an update file. In either case, 
the data saved in the input message area of the predecessor 
program is immediately available to the successor program. 


Remember, you can only perform a READ operation on the input 
message area once. If you try it a second time, the end-of-file 
indicator is set on. 


KEY OR RECORO 
ADORESS FIELO LENGTH 





OVERFLOW 
INDICATOR 

eLocKk RECORD 

vencrn ] vencrn | 


fr] 
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Figure 2-8. Defining the Input Message Area as an Update 
Demand File 
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Immediate succession saves When using the input message area to pass data between 
interface area contents programs, you must specify immediate succession in the 
termination-indicator field of the current action program. Only in 
immediate succession does the input message area remain intact 
between the time the first action program terminates and the 
successor program begins processing. Recall that in normal 
All other terminations termination, external and delayed succession, the interface areas, 
release interface areas including the input message area, are released at the termination 
of the current program. And in the case of external and delayed 
succession, the successor program gets its own set of interface 
areas. In immediate succession, however, all interface areas 
remain intact. Consequently, the data saved in the input message 
area of the first program is accessible to the successor program. 


To save input message Remember if you want to use the input message area to pass 
area data: 


> on the file description form, define it as an update file; 


> on the output form, move the data to be saved to the input 
message area; and 


> specify ‘I’ for immediate succession in the termination- 
indicator field. 
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2.12. DEFINING THE OUTPUT MESSAGE AREA (OMA) 


Purpose 


Size 


Control header 


The output message area holds the output message that your 
action program generates. It remains there until it's sent to the 
terminal. 


You must define an output message area when your program 
produces an output message. The maximum size of the output 
message area is specified at configuration. 


In addition to the output message sent to the terminal, the output 
message area contains a control header. This header is 16 
characters long and contains data generated by IMS concerning 
the output message. 
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Format of the Output Message Area Header 


Table 2-8 lists the fields that comprise the output message area 
control header. 


Summary of header fields Table 2-8. Output Message Area Control Header Contents 


1-4 Destination-terminal-id 
5-6 SFS-options 
5 SFS-type 
6 SFS-location 
7-8 Reserved for system use 
9-12 Continuous-output-code 
13-14 Text-length 
15-16 Auxiliary-device-id 
15 Aux-function 
16 Aux-device-no 
Cc'1 Device = Aux 1 
C'2' Device = Aux2 
C’3° Device = Aux3 
C4 Device = Aux4 
C’5 Device = Aux5 
C’6 Device = Aux6 
C’7 Device = Aux7 
C8 Device = Aux8 
c’9 Device = Aux9 





Output Message Header Fields 


The output message area control header contains the following 
items: 





Destination-terminal-id Destination-terminal-id identifies the terminal to receive the output 
(positions 1-4) message. If you don’t move a value to this field, the terminal that 
sent the input message receives the output message. 
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SFS-type 
(position 5) 


SFS-location 
(position 6) 


Continuous-output-code 
(positions 9-12) 


Text-length 
(positions 13-14) 


Auxiliary-device-id 
(positions 15-16) 





When you transmit an input or input/output screen using screen 
format services, IMS places a value of | in SFS-type. This means 
that the screen format can be used for input in the following 
action. You can change the screen to an output-only screen by 
placing hexadecimal zero in this field. 


To build a screen format in dynamic main storage instead of in 
your output message area, move C’D’ to SFS-location. Once you 
build a screen format in dynamic main storage and you want to 
send a message from the output message area, you must move 
hexadecimal zero to this field. Screen format services is 
discussed in Section 6. 





Continuous-output-code is a 4-character field that the action 
program uses when generating continuous output. The contents 
of this field are returned to the successor program in the input 
message area. Continuous output is discussed in Section 5. 





Text-length is a binary half-word integer that specifies the length 
of the output message. At the start of program execution, this 
field contains the configured size of the output message area. 
Before the output message actually goes to the terminal, RPG Il 
enters a new value into the text-length field. It computes this 
value by taking the end position for the last field described on 
the output form, and subtracting 12 characters (16 characters for 
the output message area header minus 4 bytes for the 
text-length field). IMS then uses this value to determine the size 
of the output message going to the terminal. This procedure is 
further described in 2.14. 





Auxiliary-device-id contains two fields: aux-function (15) and 
aux-device-no (16). The action program moves a value to 
aux-function when it generates continuous output and when it 
transmits regular output messages to an auxiliary device. 
Aux-device-no identifies the configured number for the auxiliary 
device receiving the output message. This number is specified in 
the communications network definition. 
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2.13. FILE SPECIFICATIONS FOR THE OUTPUT MESSAGE AREA 


Defining OMA as an 
output file 


Sample file description 
form coding 


Columns 15,16,19 


Columns 24-27 


Device name 


You can define the output messsage area as an output file or as 


an update demand file. 


Generally, the output message area is defined as an output file 
since most action programs generate output messages. Figure 


2-9 shows you how to do this. 


FALE PROCESSING MODE 


FILE DESIGNATION KEV OR RECORD. 


ADORESS FIELOLENGTH 


HECORD ADORESS TYPE 


EXTENSION OR 1ORDERED LOAD 
LINE COUNTER, 














Figure 2-9. Defining the Output Message Area as an Output File 


The output message area is defined as 
OUTMSG in columns 7-13. You must 
give it a unique name; you can use the 
name OMA. 


The file type (column 15) is O for 
output. Whenever column 15 contains 
an O, leave column 16 blank. The 
required entry in column 19 is F for file 
format. 


In columns 24-27, we entered 143. 
This is the configured size of the output 
message, including 16 characters for the 
control header. 


In columns 40-46 (Device), *OMA is the 
only acceptable entry. 
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Defining OMA as an update Define the output message area as an update demand file when 


demand file 


Reading text-length 


Reading data saved by 
predecessor program 


Saving data in OMA 


Output message area in 
immediate succession 


Output message area in 
delayed succession 


Determining maximum 
output message area 
size 








you want to do a READ operation on the output message area. 
Generally, you read the output message area for one of two 
reasons: 


To determine the value in the text-length field. This field 
contains the output message area size specified at 
configuration. Knowing this value is important in determining 
the size of the output message your action program can 
create. 


To get data saved there by a predecessor program using 
immediate succession. 


You can save data in the output message area with either 
immediate or delayed succession. 


With immediate succession, all interface areas of the current 
action program, including the output message area, remain 
intact for the successor program. The successor program 
needs only to read the output message area to get this data. 


With delayed succession, the output message area of the 
current action program automatically becomes the input 
message area of the successor program. Thus, the sucessor 
program has immediate access to the saved data. If the 
successor program defines the input message area as the 
primary file, RPG Il reads it as soon as processing begins. 


In Figure 2-10, all entries are the same 
as in Figure 2-9, except for columns 15 
and 16 where we defined the output 
message area as an update demand file. 
We did this in order to read the text-length field to see if the 
configured output message area size can handle the 
143-character output message this program generates. If the 
configured size is smaller than this, a portion of the message is 
lost when transmitted to the terminal. 
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ON OF 
KEY OH RECORD LINE COUNTER, 
ADORE SS FIELD LENGTH CODE 








RECOHD AODRESS TYPE 
FILE ORGANIZATION 





> OVERFLOW 
(NOICATOR DEVICE 


KEY FIELD 

starting | 

vocation |” 
38}39] 40 











Figure 2-10. Defining the Output Message Area as an Update 
Demand File 


2.14. HOW TO CODE YOUR OUTPUT MESSAGE 


RPG II moves value When an action program generates an output message smaller 

to text-length than the configured output message area size, RPG Il moves a 
new value into the text-length field before the message is sent to 
the terminal. Also, when an action program generates more than 
one message (see Section 5), RPG Il moves a value to text-length 
before each message is sent. 


How output message length RPG Il uses the end position of the last field you code on the 

& is determined output form to determine the length of the output message. For 
this reason, be sure to list last the field with the highest end 

position. You must also remember to allow 16 characters for the 

output message header when calculating the end position of the 


first field. 
Allowing for output Suppose your output message has three fields, CUSTNO, NAME, 
message header and ACCT. The first field, CUSTNO, is 14 characters long, but 


you must allow 16 characters for the output message header, so 
you give the value 30 for the ending position of the first field. 
NAME and ACCT are each 30 characters. 


Example In Figure 2-11 the field ACCT has the highest value end position, 
90, and is listed last on the output form. RPG Il computes the 
value of text-length by taking the value 90 and subtracting 12 
characters (16 for the output message area header minus 4 for 
the text-length field). Consequently, when the output message 
goes to the terminal, the three fields CUSTNO, NAME,and ACCT 
all appear on the screen since the value in text-length was large 
enough to accommodate the three fields. 
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Incorrect text length 


Effect of incorrect 
text length 





STACKER SELECT: 


ck eren OVERFLOW. TPUT INDICATORS, 


PROGRAM 
(OENTIFICATION 


Nie 
Oe 
® tor coves 





























Figure 2-11. Coding the Output Form Determines the Value in 
Message Length 


Now look at Figure 2-12. In this case, RPG Il looks at the end 
position on the output form and determines the output 
text-length field value based on position 60. RPG Il computes the 
value for the text-length field using the end position 60. 


STACKER SELECT! 


F*FETCH OVERFLOW DATA FORMAT 


Pre 


POSITION 
IN 
ourruT 

RECORD 











Figure 2-12. How Placement of Output Fields Can Cause Incorrect 
Message-Length Field 


When the output message goes to the terminal, only CUSTNO 
and NAME appear on the screen. IMS overlooks ACCT since the 
text-length size wasn't big enough. This happens even though 
the configured size of the output message area is large enough to 
hold the entire message. You control what goes to the terminal 
by the way that you list fields on the output form. 
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OUTPUT MESSAGE AREA CODING 


When program moves value If you wish, you can move a value to the text-length field. This 

to text-length value should equal the actual size of your output message plus 
four characters for the text-length field itself. RPG !! doesn’t 
override this value no matter what you specify as the last entry 
on the output form. 


When text-length=0 When message-length is set to zeros, IMS puts out the message 
“TRANSACTION COMPLETE”. 
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2.15. DEFINING THE CONTINUITY DATA AREA (CDA) 


Purpose 


Size 


File description form entries 


The continuity data area is used to pass data from one action 
program to its successor. IMS saves this area on disk at the 
termination of the predecessor action program and restores it at 
the start of the successor action program. You generally define 
a continuity data area when you want to pass data between 
action programs. 


SUCCESSOR 


ACTION ACTION 


PROGRAM CONTINUITY PROGRAM 


PROGO1 DATA 
FILE 


PROGO2 





Continuity data area size is specified at configuration. How you 
define it on the file description form depends on how your action 
program uses it (Table 2-9). 


Table 2-9. Defining the Continuity Data Area According to How 
the Action Program Uses It 








Saves Data Only 


Reads and Updates 
Saved Data 


Reads Saved Data Only 


In 2.16 we'll consider an example where the continuity data area 
is used in the three ways described in Table 2-9. 
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2.16. HOW TO USE THE CONTINUITY DATA AREA TO PASS DATA 


Example Consider a case where there is a transaction that contains three 
action programs - PROGO1, PROGO2, and PROGO3. When it 
terminates, PROGO1 wants to pass data to PROGO2. Figure 2-13 
shows how you do it. 


EXTENSION OF 
FILE DESIGNATION KEY OR RECORD LINE COUNTER ow 
ADORESS FIELD LENGTH CODE (x10) 


OF EXTENTS 
REWINO OPTION 
> OVERFLOW E CONDITIONERS 
«1 & inpicator 
OT PROGRAM 


KEY FIELO EO] IDENTIFICATION 
STARTING 


NOT USED 
PISIRIC/OIT 


= 


14} 78 


EST SD 








Figure 2-13. Defining the Continuity Data Area when It Saves 
Data Only 


Assigning file name and The file name is CDA. In column 15, the 

type entry is O for output file because at 
output we want to move data to the 
continuity data area. 





Continuity data file When an action program terminates, in this case PROGO1, any 
data in the continuity data area is moved to the continuity data 
file. It is saved there until the successor program is scheduled. In 
single-thread IMS, the continuity data file is AUDCONF; in 
multithread IMS, it is CONDATA. 


Record length and For record length we enter 240; this is 
device name the size of the saved data. In columns 
40-46, the required entry is *CDA. 


Now, consider Figure 2-14. 
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Continuity data area as 
an update file 


Passing data to PROGO2 


Passing data to final 
successor program 


Continuity data area 
as an input file 





FILE PROCESSING MODE EXTENSION OR IDEREO LOAD 
FILE DESIGNATION KEV OR 9ECORO LINE COUNTER 
ADDRESS FIELD LENGTH COOE 








RECORD ADORESS TvPE 
FILE FORMAT FILE ORGANIZATION 
> OVERFLOW 
INDICATOR 
eLocK RECORD 
LENGTH | LENGTH 


5 
S 
Q 
£ 
a 
ia 











Figure 2-14. Defining the Continuity Data Area when It Reads and 
Updates Saved Data 


Figure 2-14 is the file description form coding for PROGO2. 
PROGO2 is the middle program in this series. It is designed to 
read the data saved by PROGO1 and update it. Notice the 
continuity data area is defined as an update/demand file. 


When IMS schedules PROGO2, it moves the data saved by 
PROGO1 from the continuity data file to the continuity data area 
of PROGO2. Using the READ operation, this data becomes 
available to PROGO2 for updating. 


When PROGO2 terminates, it passes data to its successor, 
PROGO3. Figure 2-15 is the coding for the file description form 
for PROGO3, the last program in the transaction. 


FILE PROCESSING MODE EXTENSION OR JROERED LOAD 
FILE DESIGNATION KEY OR RECORD LINE COUNTER 
ADDRESS FIELD LENGTH cove 

RECORD ADDRESS TYPE 
FILE ORGANIZATION 

OVERFLOW 

INDICATOR 

eLock RECORD 


LENGTH | LENGTH = KEY FIELO 
STARTING 


° 
Fy 
= 
2 








Figure 2-15. Defining the Continuity Data Area when It Reads 
Data Only 


Figure 2-15 defines the continuity data area as a primary input 
file. When IMS schedules PROGO3, it moves the saved data of 
PROGO2 from the continuity data file to the continuity data area 
of PROGO3. As soon as PROGO3 begins processing, RPG Il 
begins reading this area. The transaction is complete when 
PROGO3 terminates normally. 
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Normal flow of saved data’ In describing this transaction, we said the saved data went to the 
continuity data file. This point needs explanation. When an action 
program defines a continuity data area, any data saved by that 
program goes to that specific area. When the program 

Continuity data file terminates, the saved data is written to the continuity data file - 
AUDCONF in single-thread IMS; CONDATA in multithread IMS. 
When the successor program begins processing, IMS moves the 
saved data from the continuity data file to the continuity data 
area of the successor program. 


Saved data flow in Only in immediate succession is this process different. Since all 

immediate succession interface areas, including the continuity data area, remain intact 
between programs, the data stored there is not written to a 
continuity data file. It remains in main storage and is immediately 
available to the successor program when processing begins. 


Other ways to save data We might mention again at this point that you can also use the 
input and output message areas to pass data when specifying 
immediate succession (see 2.11). In addition, you can use the 
output message area to pass data when using delayed 
succcession since the output message area becomes the input 
message area of the successor program (see 2.13). 


2.17. HOW TO VARY CONTINUITY DATA AREA SIZE TO SUIT AMOUNT OF 
DATA PASSED 


Changing continuity-data YOu may need to vary continuity data area size from one action 

-area-inc value program to another depending on the size of the data saved. You 
do this by changing the value of continuity-data-area-inc in the 
program information block. You can only increase the continuity 
data area size for the successor action program, not for the 
current program. 


How IMS determines IMS determines the continuity data area's size at the termination 
continuity data area size of each action program based on which length is larger: 


the CDA length specified at configuration; or 
the length specified in the continuity-data-area-inc field in the 


program information block plus the actual length of the data 
saved at the termination of the action program. 
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Increasing continuity 
-data-area size 


Updating the program 
information block 


Example 


Moving a value to 
continuity-data-area-inc 











Let’s consider once again a series of three action programs, 
PROGO1, PROGO2, and PROGO3. Assume that the configured 
continuity data area size is 1536 characters. The data you want 
to pass in PROGO1 is 1500 characters. You know that PROGO2 
will be passing the same data plus additional data to PROGOS. 
Consequently, PROGO1 needs to increase the continuity data area 
size for PROGO2, the successor program. To do this, PROGO1 
must have already defined the program information block as an 
update demand file on the file description form. On the output 
form, you specify an increment value for this field. 


Consider Figures 2-16 and 2-17. 


In Figure 2-16, we defined PIB as an update demand file since 
PROGO1 updates successor-id, termination-indicator, and for the 
purpose of this example, continuity-data-area-inc. Recall that you 
do not need to do a READ operation of the program information 
block to update it. Also, notice that the CDA is an output file 
with a configured size of 1536 characters. 


ExT 
KEY OR RECOAD LINE COUNTER 
ADORESS FIELO LENGTH COE 














roy 
inf 
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$ 
rs 
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Figure 2-16. Coding the File Description Form for Program PROGO1 


In Figure 2-17, we show the values output to the PIB file when 
PROGO1 terminates. ‘PROGO2’ is moved to successor-id (end 
position 10). ‘I’ is moved to termination-indicator (end position 
11). The hexadecimal value ‘1F4’ (500) is moved to 
continuity-data-area-inc. 
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Figure 2-17. Coding the Output Form for Program PROGO1 


Computing continuity-data At termination IMS examines all these fields. It compares the 
-area size for successor value of the continuity data length specified at configuration 
(1536) to the sum of the continuity-data-area-inc (500) plus the 
length of the data saved by PROGO1 at termination. Since the 
saved data (1500 characters) plus 500 is larger than 1536, IMS 
increases the continuity data area size for PROGO2 to 2000 


characters. 
é Continuity-data-output The actual length of the saved data is specified in the 
fength: and: continuity continuity-data-output-length field in the program information block 


-data-input-length : 
ss a aid of the current action program. When IMS schedules the successor 


program, this value is moved to continuity-data-input-length in the 
program information block of the successor program. 


When continuity-data When an action program terminates and the value in 
-area=O continuity-data-output-length is zero, no data is saved in the 
continuity data file. 








UP-9206 SPERRY UNIVAC OS/3 3-1 
IMS ACTION PROGRAMMING IN RPG II 


SAMPLE TRANSACTION 


3. Writing an Action Program 


3.1. DIFFERENCES BETWEEN ACTION PROGRAMS AND NORMAL RPG II 
PROGRAMS 


In Section 2, we discussed rules for coding action programs. 
You'll recall that the major difference between action programs 
Using interface areas and a normal RPG Il program is coding the interface areas. These 
areas are coded on the file description form. They handle all 
communication between IMS and the action program. 


3.2. PURPOSE OF EXAMPLES 


Scope of section In this section, we present a series of action programming 
examples illustrating the coding principles described in Section 2. 
These examples are not complex and they emphasize the points 
you need to keep in mind when designing an action program. 
Let’s summarize these points: 


signals the beginning of a 





input messages and produce 


output messages. 





for the handling of 
input and output messages. 


Key features of action db 
programs 





- the program information block, input 
message area, Output message area, and continuity data 
area - handle control data passing between your program 
and IMS. These areas are described in Section 2. How they 
are used is one of the major topics of this section. 





you have several options: 


screen format services; device independent control 
expressions (DICE); and, field control characters (FCCs). 
Using device independent expressions and field control 
characters is discussed in Appendix A. Screen format 
services is covered in Section 6. 
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3.3. HOW TRANSACTIONS ARE INITIATED 


Entering a transaction 
code 


How action programs are 
scehduled 


Example 


A transaction begins when the operator enters a transaction 
code at the terminal. This code tells IMS what action program to 
schedule. 


Each transaction code, and the action program that processes it, 
is specified at IMS configuration. Whenever a code is entered at 
a terminal, IMS checks the transaction table to determine if it’s a 
valid code. IMS then checks to see what action program was 
configured to process this code. Once these steps are 
completed, if resources are available, IMS schedules the 
appropriate action program. 


In our example (Figure 3-1), when the operator keys in the word 
‘START’, IMS checks the transaction table to verify the code and 
find the action program configured to process ‘START’. The 
name of this program is RCMENU. If resources are available, IMS 
schedules RCMENU; if not, the transaction code START is 
queued until IMS can handle it. 


RCMENU 





Figure 3-1. Transaction Code Initiates IMS Transaction 


3.4. SAMPLE TRANSACTION (EXTERNAL SUCCESSION) 


A sample transaction 


In this example, there are six action programs. The first program 
generates a menu. The other five programs allow a terminal 
operator to: 

p> enter an order; > bill the customer; and 


> update the customer file; > terminate the transaction 


> update the order file; 
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Summary of processing The first action program displays a menu on the terminal screen. 
The terminal operator selects the operation he wants to perform 
by entering the appropriate menu selection. The menu program 
validates the selection and displays a template on the terminal 
screen. The operator fills in the data requested and another 
action program uses the data to perform the requested operation, 
such as updating the customer file. 


We will describe the operation of two of the action programs, 
Programs RCMENU and RCMENU and RCCUST. RCMENU displays the menu screen from 
RCCUST which the terminal operator selects the operation (we assume 2 - 
CUSTOMER UPDATE is selected), and RCCUST updates the 
customer file. We will describe the operation in detail and show 
and explain the two action programs. 


3.5. A DESCRIPTION OF WHAT THE SAMPLE TRANSACTION DOES 


Our sample transaction begins with the entry of the transaction 

code START at the terminal. The transaction consists of three 

Structuring the transaction actions. Therefore, there are three input messages entered at the 

terminal and three output messages generated by the action 

@ programs. Two programs process this transaction. They are 
RCMENU and RCCUST. 


Execution of RCMENU RCMENU is the first action program in this transaction. The 
transaction calls for two passes through this program, i.e., 
RCMENU will execute, be rescheduled, and execute a second 
time. Let's look at what happens in each pass. 





On the first pass, RCMENU: 


Processing on the 1. Processes the input message coming from the terminal. On 
first pass the first pass, the input message is the transaction code - 
START. 


2. Creates an output message that is the menu screen. 


3. Reschedules itself as successor program to validate the 
menu selection the terminal operator makes. 
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On the second pass, RCMENU: 


1. 


Processes the input message coming from the terminal. This 
time the input message is the number of the menu selection 
entered by the terminal operator. In our example, the 
selection made is 2 - CUSTOMER UPDATE. 


Creates an output message that is the customer update 
screen. The screen generated relates to the menu selection 
made. In this case, it is a screen requesting data to update a 
customer account balance file. 


Schedules the appropriate successor action program to 
process the data entered on the second output screen. In 
our example, the successor program is the customer update 
program RCCUST. If a different menu selection is made, 
RCMENU generates the appropriate screen as an output 
message and schedules the appropriate successor program 
to process it. 





When RCMENU terminates after the second pass, RCCUST 
begins processing (we are assuming, of course, that the terminal 
operator chose menu selection 2). RCCUST: 


I: 


Processes the data the terminal operator enters on the 
customer update screen generated as output by RCMENU on 
the second pass. 

Computes a new balance for the customer account file. 


Updates the customer account file. 


Creates an output message containing the new customer 
balance to be sent to the terminal. 


Figure 3-2 illustrates the processing for RCMENU and RCCUST. 
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RCMENU 
(PASS 1) 


RCMENU 
(PASS 2) 


CUSTOMER 
UPDATE 


RCCUST 
DATA AND 


ACCOUNT 
BALANCE 





Figure 3-2. How RCMENU and RCCUST Process a Transaction 


3.6. GENERAL OPERATION OF ACTION PROGRAMS 


Action program design 


Common characteristics 


Although the actual processing done by RCMENU and RCCUST 
differs somewhat, the activities involved are fundamentally the 
same. The terminal sends an input message. The action program 
processes it and generates an output message. The action 
program then schedules a successor program, if needed, and 
terminates. 


These activities are characteristic of action programming. 
Whether one or many action programs are involved, the basic 
design is the same. Action programs process input messages 
and generate output messages. 
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3.7. EXPLANATION OF THE CODING FOR RCMENU 


Formatting output 


With this general background, let's now look at the actual coding 
for this transaction, beginning with RCMENU. Figures 3-3 and 
3-4 show compilation of the RCMENU and RCCUST action 
programs. 


Note on the output form of both programs that a series of device 
independent control expressions and UTS 400 field control 
characters are used to format output messages sent to the 
terminal. To facilitate our discussion of the action programs 
themselves, we'll ignore these sequences for the time being. A 
discussion of device independent codes and _ field control 
characters can be found in Appendix A. Section 6 discusses how 
action programs use screen format services to format output 
messages. 
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Figure 3-3. RCMENU Program (Part 1 of 2) 
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Figure 3-3. RCMENU Program (Part 2 of 2) 
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Figure 3-4. RCCUST Program (Part 1 of 2) 
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Figure 3-4. RCCUST Program (Part 2 of 2) 
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RCMENU CODING DESCRIPTION 


@ 3.8. RCMENU - ASSIGNING A NAME TO THE PROGRAM 


Every action program requires these entries on the control form: 


Control form entries 





Designates an action ee | 


Action program name een 


3.9. RCMENU - DEFINING THE INTERFACE AREAS (IMA, OMA, and PIB) 


The file description form describes all interface areas your action 

Define only areas used program references. The action program defines only those areas 
it intends to use. We describe in detail the use of the interface 
areas in Section 2. 


RCMENU uses three interface areas - the input message area 

(IMA), output message area (OMA), and program information 
@ block (PIB). Since RCMENU does no file processing, no user files 

are described; however, the interface areas are treated as files. 


The following table describes the file description coding that 
defines the IMA, OMA, and PIB associated with RCMENU. 


Defining the input 
message area (IMA) 








7-13 User file name assigned to the input message area. 

15-16 Primary input file. As soon as IMS schedules RCMENU, and 
assigns its interface areas, it places all data entered at the 
terminal in RCMENU’s input message area. When RCMENU begins 
executing, it immediately reads the data in the input message area 
into the program. 

19 Required entry 

24-27 This is the configured size of the input message area. 

You specify input message area size in the INSIZE parameter in 
the ACTION section of the IMS configuration. 

RCMENU isn't expecting a message larger than 48 characters. 
However, IMS does make allowances to accommodate larger 
messages. 

40-46 Required entry whenever defining the input message area. 
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RCMENU CODING DESCRIPTION 








Defining the output 
message area (OMA) 








User file name assigned to the output message area. You must 
define an output message area if the action program creates an 
output message. This area holds the output message that 
RCMENU creates. 






Output file 







Required entry 






This is the maximum size of the output message RCMENU can 
generate. As coded, the program doesn't use all 500 characters. 


You specify output message area size in the OUTSIZE parameter 
in the ACTION section of the IMS configuration. 






Required entry when defining the output message area 





Defining the program 
information block (PIB) 
User file name assigned to the program information block. You 
only define this interface area if you intend to read it or read and 
update it in your action program. Whether or not you define it, 
RPG Il checks the status and detailed status codes fields in the 
program information block after each I/O request and makes the 
values in these fields available to the action program. These 
codes inform the action program if the function request made to 
IMS was successful or not. If not, both the status- and 
detailed-status-code fields (1~4) in the program information block 
and *ERROR contain the reason for the failure. 





15-16 Update demand file. Since RCMENU updates the program 
information block, it must define it as an update demand file. At 
output, RCMENU moves values into the successor-id and 
termination-indicator fields. At action program _ termination, 
successor-id identifies to IMS the name of the successor action 
program. Termination-indicator identifies the type of termination 
for the current action program. 


19 Required entry 


24-27 This is the entire program information block area accessible to an 
action program. Other areas are for IMS use only. For a complete 
list of the program information block fields you can access in your 
program, see 2.5. 





40-46 Required entry whenever defining the program information block 
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RCMENU PROCESSING 


3.10. CONTENTS OF MAIN STORAGE AFTER RCMENU IS SCHEDULED 
When IMS schedules RCMENU, this is the way main storage 


looks. Notice in Figure 3-5 that the three interface areas defined 
by RCMENU are loaded with the action program. 


PROGRAM OUTPUT INPUT 


INFORMATION MESSAGE MESSAGE 
: BLOCK AREA AREA 


RCMENU 





Figure 3-5. Main Storage when IMS Schedules RCMENU 


3.11. HOW RCMENU USES THE INPUT MESSAGE AREA (PASS 1) 


Only one input file is defined for RCMENU - IMA or input 

Reading the input message Message area. When RCMENU begins executing, it reads the 

ate input message area. This area always contains a 16-character 
control header (see Table 2-10 for a description of the header) 
and the input message transmitted by the terminal operator. On 
the first pass through RCMENU, the input message is the word 
START. START is the transaction code that signals the beginning 
of the transaction and identifies to IMS the name of the first 
action program, RCMENU, to process this transaction. 


Once RCMENU reads the input message area, it compares 
positions 17, 18, and 19 to the characters S, T, and A. 
Contents of the input Remember to always allow positions 1-16 for the input message 
message area - Pass 1 area header. Any input message (transaction code or other data) 
entered at the terminal always starts at position 17 or some 
position thereafter. 








UP-9206 


RCMENU PROCESSING 





Characters match, 
RCMEWNU scheduled 


IMA contents 


Menu screen sent to OMA 


IMS handles 1/O 


Menu screen passed 
to terminal 


Summary - RCMENU 
Pass 1 
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In this example, the characters will match since S, T, and A are 
the first three letters of the transaction code that caused IMS to 
schedule RCMENU. When positions 17, 18, and 19 = S, T, A, 
indicator 20 is set on. 


Figure 3-6 shows the contents of the input message area when 
RCMENU is scheduled. 


HEADER 





Figure 3-6. Contents of the Input Message Area - Pass 1 


Since there are no calculation specifications for this program, 
when indicator 20 is on, detail output is done. The output is the 
menu screen that goes to the output message area where it 
remains until RCMENU terminates. No output message generated 
by an action program, be it through exception, detail, or total 
time output, ever goes to the terminal before the program 
finishes all processing. IMS handles the actual input and output of 
messages. 


In this example, when RCMENU generates the menu screen, 
processing is also complete. Consequently, the program 
terminates, rescheduling itself with external succession, and the 
menu screen is transmitted to the terminal. 


So, on the first pass RCMENU processes the transaction code 
START and produces a menu screen that IMS transmits to the 
terminal when RCMENU terminates. 


3.12. HOW RCMENU USES THE INPUT MESSAGE AREA (PASS 2) 


Processing operator menu 
choice 


On the second pass through the program, position 17 of the 
input message area is matched to the character S. It doesn't 
match. The program then tries to match position 17 with the 
number 1,2,3,4, or 5. The numbers 1-5 represent possible menu 
choices the terminal operator can make. 























UP-9206 SPERRY UNIVAC OS/3 3-15 
IMS ACTION PROGRAMMING IN RPG tI 


RCMENU PROCESSING 


Processing input message On the second pass, RCMENU is expecting one of these numbers 

area contents — Pass 2 in position 17 of the input message area. If the operator has 
followed directions correctly, this is what the program receives. If 
not, any other input entered from the terminal sets on indicator 
99, which like indicator 20, retransmits the menu screen. The 
operator then has another chance to make the correct entry. 


Figure 3-7 shows the contents of the input message area when 
the operator enters valid data. 


| HEADER 





Figure 3-7. Contents of the Input Message Area — Pass 2 


@ Indicator set on When FPG I! finds the number 1,2,3,4, or 5 in position 17 of the 
a input message area, a specific indicator is set on and a specific 
type of detail output occurs. Once again, there are no calculations 
to be done. Table 3-1 summarizes the indicators set on and 
resulting output, based on the menu selection made. 


Table 3-1. Indicators Set On During Second Pass 
through RCMENU and Resultant Output 





S, T (18), A (19) Menu screen 


1 Order entry screen* 


2 Customer update screen 
3 Order update screen* 

4 Billing screen* 

5 Stop 


None of the above Menu screen 


*Output coding not shown in example 
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3.13. HOW RCMENU USES THE OUTPUT MESSAGE AREA 


RCMENU'S output at Output for action programs is defined the same as for any RPG Il 
program termination program, even the output message destined for the terminal. The 
important point, however, is that no output generated by an 
action program goes to the terminal until the program terminates. 


Two output messages Looking at the output form coding (Figure 3-3), you see that 
RCMENU generates two output messages destined for the 
terminal, one on each pass through the program. 


Message formatting All the hexadecimal sequences interspersed among the output 
fields format the message when it appears at the terminal. These 
sequences are discussed in Appendix A. 


Generating the Output Message — Pass 1 


Screen generated for Figure 3-8 shows the output message that goes to the terminal 
Fass 4 when RCMENU terminates after the first pass through the 
program: 





SPERRY UNIVAC 
MENU SELECTION PROGRAM 
1- ORDER ENTRY 
2- CUSTOMER UPDATE 


3- ORDER UPDATE 
4~ BILLING 
5- STOP 


ENTER YOUR SELECTION [{ } 
PLACE CURSOR HERE TO TRANSMIT [ ] 





Figure 3-8. RCMENU’s Output Message - Pass 1 
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Generating the Output Message — Pass 2 


Screen generated for When the menu selection is 2-CUSTOMER UPDATE, indicator 40 
Pass 2 is set on and RCMENU generates the output screen in Figure 3-9. 
This occurs on the second pass through RCMENU. 


SPERRY UNIVAC 
CUSTOMER UPDATE PROGRAM 


ENTER 5-DIGIT CUSTOMER NUMBER 


ENTER + FOR PAYMENT MADE 
ENTER - FOR PAYMENT OWED 
ENTER + OR - _ 

ENTER AMOUNT 


PLACE CURSOR HERE TO TRANSMIT _ 





Figure 3-9. RCMENU’s Output Message on Pass 2 for Menu Selection 2 


Menu selections 1, 3, We have not included output message screens when indicators 

and 4 30,50, and 60 are set on (menu selections 1,3, and 4). Such 
screens would be designed on the order of the customer update 
screen; however, they would request data relating to order entry 
(1), order updating (3), or billing (4). 


When No Output Message is Generated 


Ending the transaction When indicator 70 is set on (menu selection 5), we move zeros 
into the text length field of the output message area. This causes 
IMS at program termination to send out a standard system 
message indicating that the IMS transaction is over. See Figure 
3-10. 


TRANSACTION COMPLETE 





Figure 3-10. RCMENU’s Output Message when Menu Selection ‘5-—STOP’ Is Made 
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3.14. HOW RCMENU USES THE PROGRAM INFORMATION BLOCK 





Updating the program The only other output file described on the output form is the 

information block program information block. It shows what values -RCMENU 
moves into successor-id and termination-indicator at output. 
Successor-id occupies positions 5-10 of the program information 
block and identifies to IMS the name of the successor action 
program. Termination-indicator occupies position 11 and 
indicates to IMS the type of termination for the current action 
program. The types of termination are normal, external, delayed, 
immediate, abnormal, and abnormal with snap dump. For more 
information on these termination types, see 1.4. 


Defining the location of Whenever you define program information block fields in your 

program information action program, make sure that their beginning and end positions 

Dlecie aee correspond exactly to their predefined location in the program 
information block. Table 2-6 defines these locations. 


Indicating successor-id Depending on what indicator is set on at output, the appropriate 

and termination type values are moved to successor-id and termination-indicator in the 
program information block. Table 3-2 summarizes the successor 
program name and termination type when a specific indicator is 
set on. 





Table 3-2. Successor Programs and Type of Termination 
Corresponding to Each Indicator Set On 















RCMENU External 


ORDENT External 


RCCUST External 


ORDRUP External 
BILLS External 
No Successor Normal (N) 





RCMENU External 
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IMS termination procedures \When output is complete, RCMENU terminates since there is no 
further processing to be done. IMS then checks the output 
message area and sends the message to the terminal. IMS also 
checks successor-id and termination-indicator to determine if 
further processing is required. When the terminal operator 
receives the output message and enters data to the screen, IMS 
then schedules the successor program to process it. 


Determining successor On the first pass through RCMENU, the successor is RCMENU. 

program and type of On the second pass, the successor corresponds to the menu 

eee selection made. In our example, the successor is RCCUST - the 
program that processes the customer update screen. RCMENU 
terminates with external succession. This means that IMS waits 
for an input message from the terminal before it schedules 
RCCUST. That input is the data entered by the terminal operator 
on the screen labeled SPERRY UNIVAC CUSTOMER UPDATE 
PROGRAM (Figure 3-9). When IMS receives the input message, it 
places it in a queue and schedules RCCUST as soon as resources 
are available. 
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3.15. EXPLANATION OF THE CODING FOR RCCUST 





Earlier, we summarized what RCCUST does. To refresh your 
memory before examining the code, let’s review its functions: 







_ input data entered on the customer update screen 
and validates it. 


Processing for RCCUST new balance for the customer account. 


he customer account file, CUSTFIL. 


d 
> 
> 





an output message to be sent to the terminal. 


3.16. RCCUST — ASSIGNING A NAME TO THE PROGRAM 





Control form entries The control form entries are an 
name in columns 75-80. 


n column 74 and the program 


3.17. RCCUST — DEFINING THE INTERFACE AREAS (IMA, OMA, PIB) 


Unique set of interface areas The file description form defines the three interface areas and the 

for RCMENU and RCCUST one user file, CUSTFIL, referenced by RCCUST. The input 
message area (IMA) is defined as in RCMENU. The only 
difference is that the configured size is larger - 100 characters 
(columns 24-27) - to allow for a larger input message from the 
terminal. The output message area (OMA) and _ program 
information block (PIB) are defined exactly as they are in 
RCMENU. Remember, however, that although these areas are 
defined identically and that RCCUST directly follows RCMENU, 
RCCUST has its own unique interface areas assigned by IMS 
when the program is scheduled. 


Using the same interface The only time a successor program uses the same interface 

aoa? areas as the predecessor program is when | for immediate 
succession is specified in the termination-indicator field of the 
predecessor program. 


User file — CUSTFIL There is only one user file described for RCCUST, CUSTFIL. It is 
an indexed file that will be processed randomly using its 
5-character key field. 
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3.18. DEFINING THE INPUT FIELDS 


Defining input fields The input form describes input fields for two files: the input 
message area (IMA) and the customer file, CUSTFIL. Like other 
RPG Il programs, action programs only describe input fields they 
reference in the program. 


Reading the input When RCCUST begins executing, it reads the input message 

MESnAserares area. Indicator 01 is set on. The input message area contains the 
data entered by the terminal operator on the customer update 
screen. The fields defined as CUST, SIGN, and AMOUNT come 
into the program. These fields occupy positions 17 through 27 of 
the input message area. The first 16 positions contain the 
header. If the field SIGN contains a zero or a blank, indicator 20 
is set on. Figure 3-11 shows the contents of the input message 
area when RCCUST begins processing. 


HEADER 


SPERRY UNIVAC (1-16) 


CUSTOMER UPDATE PROGRAM 
ENTER 5-DIGIT CUSTOMER NUMBER 12596 


CUST (17-21) 


ENTER + FOR PAYMENT MADE 
ENTER - FOR PAYMENT OWED 
ENTER + OR - + SIGN (22) RCCUST 
ENTER AMOUNT 20000 
AMOUNT 
PLACE CURSOR HERE TO TRANSMIT (9a) (23-27) 





Figure 3-11. Input Message Coming into Program RCCUST 


CUSTFIL fields The input form also describes input fields for CUSTFIL. CUSTFIL 
is the user data file. Its key field CUSTID is a 5-character field 
that begins in position 1. The other five fields described for 
CUSTFIL occupy positions 6-65. Notice that the field BALDUE is 
a packed decimal field. 





UP-9206 
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3.19. CALCULATIONS FOR RCCUST 


Validating the customer 
number field 


Validating the sign field 


Validating the amount field 


When a payment is made 


When a purchase is made 


Now let’s look at the operations RCCUST performs. 
Validating Input 


The 5-digit customer number entered as input at the terminal is 
used to chain into CUSTFIL. The customer number corresponds 
to the key field CUSTID in the input message area. If the number 
entered at the terminal doesn’t match any of the keys in the 
index for CUSTFIL, indicator 30 is set on and detail output is 
done. 


Next, RCCUST compares SIGN to ‘+’ or ‘-’. If SIGN equals +, 
indicator 41 is set on. If SIGN equals —- , indicator 42 is set on. If 
SIGN is not +, -, or blank (indicator 20 was set on), indicator 50 
is set on and detail output is done. 


Next, RCCUST tests AMOUNT to determine if it is numeric. If it 
is, indicator 60 is set on; if not, 70 is set on. When 70 is on, 
detail output is done. When AMOUNT is numeric (indicator 60 is 
set on), RCCUST moves AMOUNT to AMT, the result field. 


Computing a New Account Balance 


Once the input data is validated, the following calculations take 
place: 


When indicator 20 or 41 is on (SIGN = blank or +), AMT is 
subtracted from BALDUE. The result is NEWBAL. This means 
that the customer made a payment to his account. The SUB 
operation credits that amount to the customer's account and 
computes the new balance. 


When indicator 42 is on (SIGN = -), AMT is added to BALDUE. 
The result is NEWBAL. This means that the customer made 
another purchase. The ADD operation adds the amount of the 
purchase to the existing balance and computes the new balance. 


3.20. OUTPUT CODING FOR RCCUST 


Output generated for 
RCCUST 


Once calculations are complete, detail output occurs. Depending 
on what indicators are set on, RCCUST creates an output 
message. Table 3-3 shows the output message that goes to the 
terminal based on what indicators are set on. 
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RCMENU CODING DESCRIPTION 


@ Table 3-3. RCCUST Indicators Set On and Resulting Output 





Output messages 





» NAME- SHANA GABRIEL All data entered at the terminal 

. ADDRESS- APPIAN WAY was valid. In this case, the 

: — CITY-ST- GENEVA, OHIO entry for SIGN was + indicating 
— 43727 the customer made a $200.00 
OLD BALANCE - $586.25 payment to her account. The SUB 
TRANSACTION - $200.00 | operation was performed and a 
NEW BALANCE - $386.25 | new account balance computed. 


INVALID CUSTOMER ID The customer number entered at 
the terminal was invalid. It didn't 
match any of the keys in the 
index for CUSTFIL. 


INVALID SIGN The entry for SIGN wasn't +, - 
or blank. 
INVALID AMOUNT The entry for AMOUNT was either 


not numeric or was less than five 
digits. If the terminal operator 
entered more than five digits, 
RPG Il truncates from the right. 


& Reinitiating the transaction Line O54 repositions the cursor so that at the end of the 
transaction when the output message goes to the terminal, the 
-cursor is at row 1, column 6. This positions it immediately after 
the word START, the transaction code, which is still displayed at 
the terminal. By simply pressing TRANSMIT, the transaction code 
START is retransmitted to IMS and the whole series begins 
again. 
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ADVANCED PROGRAMMING EXAMPLE 


4. Writing a More Complex 
Action Program 


4.1. GENERAL DESCRIPTION OF SAMPLE PROGRAM 


More detailed examples 


A sample transaction 


New features presented 


Now that we've developed some familiarity with the basic design 
of the action program in Section 3, we can study some more 
detailed examples. The structure of the action program discussed 
in this section is the same as before: it processes input 
messages and produces output messages. Now, however, the 
coding is somewhat more complex and introduces techniques 
that can be very useful to the applications programmer. 


As in the example discussed in Section 3, this transaction also 
begins with a menu program, JAMENU. Because of its similarity 
to the menu program described in detail in Section 3, we won't 
discuss JAMENU. Instead, we'll concentrate on its successor 
program, JAADD1. Since we've already given a good deal of 
attention to the basic coding of an action program in Section 3, 
we won't stress those same features here. Rather we'll 
concentrate on the new action programming tools it introduces 
and how they are used. 


Let's begin by 
introduces: 


JAADD 1 





JAADDI uses the continuity data area to pass data between 
action programs. 


VW 


It also uses internal subroutines. 


It uses an error message file. 


vy 


And, it uses screen format services to format output 
messages. 
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ADVANCED PROGRAMMING EXAMPLE 





4.2. A SUMMARY OF JAMENU’S PROCESSING 


Figure 4-1 shows the output message screen JAMENU generates 
on the first pass through the program. 


06/23/81 06:49:28 JASMENU 02/09/81 
ENTITLEMENT ACCOUNTING SYSTEM 
SELECT ONE (1) OF THE FOLLOWING OPTIONS: 


1. ADD A NEW CUSTOMER RECORD. 
*2. UPDATE CUSTOMER NAME/ADDRESS INFORMATION. 
*3. UPDATE BRANCH CUSTOMER INFORMATION. 
*4, UPDATE CUSTOMER ENTITLEMENTS. 


*5. OELETE A CUSTOMER RECORD. 

*6. DISPLAY CUSTOMER INFORMATION. 
« LIST ALL ACCOUNTS (ON THE WORKSTATION). 
« ENTER WORKSTATION ACTIVITY RECORDS. 
« LOGOFF SYSTEM. 


* INDICATES CUSTOMER NUMBER REQUIRED 
MENU SELECTION: __ 
PLACE CURSOR TO TRANSMIT ([_] 





Figure 4-1. Screen Generated by JAMENU 


Processing the menu Like RCMENU, JAMENU schedules itself as successor program 

selection and processes the menu selection entered on the screen. In our 
example, we assume the menu selection is 7. ADD A NEW 
CUSTOMER. To process this menu selection, JAMENU moves 
the name JAADD1 to successor-id and | to termination-indicator. 
When JAMENU completes all processing, the program 
terminates. IMS checks the successor-id and termination-indicator 
fields and immediately schedules JAADD1. 


4.3. A SUMMARY OF JAADD1, THE SAMPLE PROGRAM 


The structure of the JAADD1 is the first of two action programs required to add a 

fansacon new customer and account record. JAADD1 validates the data 
used in the update. Its successor program, JAADD2 validates 
more data and does the actual file updating. We will discuss 
JAADD1 only since the two programs are very similar. However, 
we will include the coding for both programs to give you a fuller 
appreciation for the entire operation. The coding, output screen 
1, and output screen 2 for JAADD1 are found in Figures 4-2, 
4-3, and 4-4, respectively. Figure 4-5 is the coding for 
JAADD2. 
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JAADD1 CODING 


U § 7 9 13 17 61 69 


ADD NEW CUSTOMER SOR JAADD) 
GoooliH 


THIS PROGRAM IS THE 1ST OVERLAY TO BE CALLED IF THE MFNU 
COONGF « SELECTION WAS TO ADD A CUSTOMER RECORDe THE 1ST TIME THRU, 
COCOSFs* THE *JA¢ADD1* SCREEN WILL BE PUT OUT AND THIS PROGRAM WILL 
CCUCEF* SUCCEED TO ITSELF. AFTER THE SCREEN IS TRANSMITTED BACK INy 
ICC C7Fs THE CUSTOMER NUMBER AND ACCOUNT CODES ARE CHECKED FOR 
DOCCEF » VALIDITY (ASSUMING THE W/S OPERATOR DION*T WANT TO PETUPN 
COOCOFs TO THF MENU). IF THE CATA IS GOOD THE NEXT OVERLAY WILL 
Seolors 3° CALLEG TC 00 THE ACTUAL ACDING OF THE RECORDS. 


G°Cl1Fs* 

s%O12F% 

UICI3F* InOICA TORS 
uPGISFe 

UTGISF » 

C %u16F « PSOSRAM INFORMATION BLOCK 

GOOITS * INOUT MESSAGE AREA 

Q°C 18°F * 2 CONTINUITY DATA APEA 

SNU19F w CUSTOMER MASTER RECORC 

GACLOF « CUSTOMER PECORC DELETED 

JAS21LF* ACCOUNT CROSS-REFFRENCE RECORD 

OPCP!Fm { SYSTE™ CONTROL ERROR TEXT RECORD 

UTGL IF se ERROR TFXT RECORG DELETED 

uMO24F x : 1ST TIMF THRU PFOGRAM (CALLOEOD BY JAMENU)D 

we "LeSF + 2ND TIME THRPU PROGRAM 

OTU?6F* ? w/S CSESATOR CHOSF TO RETURN TO THE MENU 
GOCSTE® FE. GENFRAL PURPOSE INDICATOR - LOCAL USASE 
OTUCBF = CUSTOMER NUMBER ZERO AND /OR ACCOUNT CODF BLANK 
DOG? 9E* CUSTOMER NUMBER ALREADY EXISTS IN CUSTMST 
COLZGF# ACCOUNT CODE ALREADY EXISTS IN XREFI 


LILILF = GINFRAL EPROR INGICATOR 

TTPO & ¥ SYSTEM CONTROL PECOPG NOT FOUND 
eIG33F # 
SNG3HFPIE 
uCGTSFIVMA 
IGGI6F OMA 
ONCITECTA 
ECGSBFCUSTMST 
SPOZ9FXREFL 
GOG4GFSYSCTL 
oVOSLIPTS 
oro4szt S4YOPBDATE 
uTCc4s3I 6UCPBTIME 
COLSGTIMA uo? 

uNG45T 22 IMACCT 


shbe9t BET EMRAZ 


SPCual 81 IMADRI JAAND! 
sPG4GT 131 IMADR2 JAANDI 
GOCCSOT 116 IMCITY JAADDY 
sCosit 118 IMSTE JAADDI 


76 *PTe 
135 #IMA 
4596 *OMA 
148 =COA 
2t6 2569 FAT nNIsc S 
1s o1OF YAT DISC S 
64 64P EAT NIsc S 


cmnaA ATT 





Figure 4-2. Action Program JAADD1 (Part 1 of 5) 
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JAADD1 CODING 
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oous2! L2301MZIP JAADD1 
OCGS3T 1260IMAREA JAAND! 
onos4T 127 13301 MPHON JAAnD1 
ucosst 134 IMMENU JAADD 
ONO56T 135 IMXMIT JAADDY 
s7GS7TTCSA JAAND! 
cNOS8I 4 COPSWO JAADD? 
CNES9T 29 CDMSEL JAANDI 
oCGagT 359CDCUST JaaDD! 
C°Selt 39 CDACCT JAADDI 
CA62T GONCEPASS JAANDI 
YIALEST 41 CDOSTAT JAADOL 
ONE4T é 47 COCPGM JAADDI, 
ePULBSICUSTMST NE & Jaap! 
oMGe6e! AR JAADD 
E7ceé7t 4 CMACCT JAADD! 
COOGEE IXRFEF) NS -€ JAADDI 
aNGegT eOx1CuUsT JAANDI 
LIU7SISYSCTL NS ; JaalD!) 
ePGI1T CR “ JAADDT 
Un 72T 56 SCERR JAADD! 
LIO73C SENTRY eWHICH PASS? JAAD 
UU THC : BUILS el ST JAADDI 
uIG7SC TMYENL oe TOeRETURM TO JAATD! 
SPO7EC RETURN oMENIT? JAAND! 
eluttt $CUST eCUSTH/SACCT JAAND! 
LPC7TEC $ BUILD eVALTD? YES JSa001 
Srergoe SEREOR eNO GET MSE JAAnD! 
wv IRC RETURN JAADD) 
LM BAC JAADD! 
Ls 2¢ PIB JAADD! 
LMCR3C PRDATE WEKEN JAADDI 
oTBR4C gTEFOT eMAKF NATE MODY YAANDI 
uPgRsSc WRKEN PRDATE JAADD? 
GCGUs6C RETUPR JAADDY 
TIQETC JAAPDI 
UNUEBC es : JAADDI 
CnC89C* GEFINE wOPK AFEAS JAAND? 
GNCSEC + JAADDI 
SPCOLCLFNLR “OVE xear? WRK2 JAANDI 
CVMIZCLENLR MOVE X*47* WoKG JAADDIY 
GTCOZCLENLR MOVE x"4re WRK6 JAANDI 
SILSYCLONLR MOVE x*4n? wRKSJ i JAADD1 
CICFSCLANLA MOVE x*4act BLANKS JAADD! 
CCUS6CLPNLR MOVE X*FE?® WRKON JAAND! 
5STO9TC « JAANDI 
CCEIBC* CHECK COA FOR NUMSEPR OF TIMES THRU THIS JAADD! 
ueg99Cw JAADDL 
uNItocse TENTPY BEGSF JAADOL 
CELAICSP SETOF 77189 JAADD) 
sTLG2csr READ CDA JAADDI 





Figure 4-2. Action Program JAADD1 (Part 2 of 5) 
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JAADD1 CODING 





l 5 7 9 


GOLO3CSR 
OVNN4CSP 79 
SO10SCSP 73 
GP1n6CSP 
CN1LOTCSR 
G108C# 
GOLN9Cs CHECK 
uM1l1cC-= 
£0111C$P 
C%112CSR 
wTL13CSF 
CALIYCSRNSS 
G7115CSR 85 
UTL1LECSF 
SOLIICSPHES 
S7118CS° 
LOLLOCSPNBS 
et123CSE5 
um1L21CSF 
yOl22cor 
COL23CGF 
LAUL2KCSR 
gT125C* 
oPL?6Cx 
ullr7cs 
POV>2ecser 
utl?9CsP 
SV13UCSF 
UCL3LCsP 
yPLTECSE 
UNLZ3TSe 
CFU3S4CSPR 
CTLESCSF 
UNL 76C5P 
OM1L37C%¥ 


13 


as 
26 
a7 


GET 


UPMLISCe FOF ORMAT 


uO1L39C* 

FALYQCSE 
JOLSICSR 
GOLSzcsF 
UM43CSP 
GP144acse 
CULSEOm 


O7™14960e SOME FRPCR HAS OCCURED - 


utle7ce 
CM14RBCPIS 
ud14a9S 
LDLECO 
cCOLSLCOMA 
uTLE2O 


17 21 


COPASS 


25 29 33 


COMP O 

MOVE 1 

GOTO SENTEX 
ComMP 1 
ENODSP 


37 41 45 49 53 57 


COPASS 


CDPASS 
SENTEX 


71 


7O01ST TIME 


CUSTOMER MASTER + ACCOUNT X-REFERENCE FOR DUPLICATES 


€CUST BEGSR 

SETOF 

COMP xX*ure 
COMP CG 

GOTO SCUSEX 
CHAINCUSTMST 
SETON 
CHAINXPETY 
SETON 

TAS 


IMACCT 
TMCUST 


IMCUST 


TMACCT 


ZTCUSFX 


SETON 
ENDS9 


EPROR MESSASE FOR EPROR OVERLAY SCREEN 


TEORAR A=ZesOP 
MOVEL*EM® 
MOVE *2O3° 
MOVE 
MOVE 
MOVELWSKG 
CHAINSYSCTL 
MOVE X*Uc3e* 
END SR 


WRKG 
WOKE 
wRKG 
WRK 
WRKE 


"76° 
on7e 


90 
OMTEXL 2 


OATE FIELD FFOY YN™ To MrY 


RRERET BoeSl 
MOVELWFKEN 
“YLT 196 
MOVE WKS 
ENOSR 


WRK 
WRKEN 
WRKON 


WL RKEN 


c &? 
1c 


ll 


*JAMENU® 
ere 
Fa 89 


KB *JATEOR® 


JPls3o*# OVERRIOE TEXT LENGTH 


Figure 4-2. Action Program JAADD1 (Part 3 of 5) 


858687 
BSeFIELOS 
85 eMANDATORY 


eDUPLICATE? 
e YES 

eACCT CONE 

eDUPLICATE? 


eE PROP? 


eT® XT LENGTH 


eSAVFE YEAR 
eSHIFT LEFT 
eNOW MMDNYVY 


PUT OUT ERROR OVERLAY SCREEN 


73 





7780 


JAADDI 
JAADDI 
JAADD 
JAADDI 
JAADDI 
JAADDI 
JAADDI 
JAADDI 
JAADDI 
JAAND1 
JAANDY 
JAADDI 
JAADDI 
JAAOD? 
JAADD 
JAAOD! 
JAANDI 
JAACOY 
JAADND! 
JAANO! 
JAAPDI 
JAANDI 
JAANDI 
JAAPDY 
JAAND! 
JAAND! 
JAADDI 
JAADOL 
JAADDY 
JAADD! 
JAAND 
JAADNDI 
JAADD! 
JAANDI 
JAAND) 
JAAND! 
JAADD! 
JAADDI 
JAADD! 
JAADDY 
JAADDI 
JAANDI 
JAADDI 
JAANDL 
JAANDI 
JAADD! 
JAAPD! 
JAANOD1 
JAANDL 
JAAND! 
JAADDI 
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091540 OMTE XL 14 JAADDI 
GN1550 NOOSCERA 66 JAANDI 
wIlS6QClA JAADDI 
£91570 4o Ae JAAND! 
091580 41 X*FF® JAADD! 
531590 47 *JAADDI® JAAND 
yO01600% JAADOL 
GT1610*" 1ST PASS = CALL YOYPSELF AND PUT OuT 1ST ADD SCREEN JAADD! 
CI1620*" JAAND? 
JTlEZ30PTS = Tae JAANDI 
71646 1L *JAAUDI* JAADDI 
57165C 11 *e* JAAND! 
UT1SECOMA : JAADDY 
£71679 K& *JATADD1® JAADDI 
oO1EEO PBmATE 22 JAANDI 
201690 PBRTIME 28 JAADDI 
STL 79CCCA ; JAADDI 
wTL71¢ CDPASS 4g JAAND! 
GT1726 41 xeune JAAD 
QPLT3C 47 *JAADDL® JAAND? 
UC174O™ JAAPRDI 
c717508 J THE GPEPATIP WANTS TO GG FACK TO THE MENUesee Ow, FT WILL JAADDI 
L1176Cs JAAPD! 
SILTTOP LE 79 JAADD! 
sM1lTEc lu *JAMENU® JAANDI 
sD1799 11 °r° JAAND) 
AwSLRCOCTA 79 JAANDI 
272810 ay fre JAAND! 
SCLP2C 41 xc? JAA0Dt 
US 3¢ 47 *JAALOL? JAADD!? 
TPLRS4Oe JAAD! 
OOLESQs EVERYTHING LOCKS CK - CALL NEXT OVEPLAY JAANDI 
719602 JAAPDI 
ST LS7CR TF c TINTINES JAANDI 
em 1ses *"JAADD2° JAATO! 
uM1390 *f JAAPDY 
LVMFLOOMA : JINTONED JAADD! 
Lmiols *JASADDZ® JAAND! 
CTL9El PBDATE 2 JAANO!I 
C°1S36 PETIME 2 JAAND! 
cCAS4OCHA PINTONESD JAADD! 
erTrese IMCUST JAADDI 
LF1960 IMACCT JAADD! 
IM1LG7C CDOPASS JAAMD? 
wF1l96O x*o0'* JAADDY 
vF1990 “*JAADD1" JAADD! 
ut2c00 IMNAME JAAND! 
aPenin TMADPI JAADD 
ul2rec IMAD&2 JAADDY 
o°2230 IMCITY JAADOL 
oh2r4od IMSTE JAADDI 





Figure 4-2. Action Program JAADD1 (Part 4 of 5) 
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JAADD1 CODING AND OUTPUT 


U § 7 9 13 17 37 4 45 49 69 73 77 (80) 


u%2950 IM2IP 142P JAANDD 
622760 TMAREA 144Pp JAAND! 
un2n7o TMPHON 14eP JAADDI 





Figure 4-2. Action Program JAADD1 (Part 5 of 5) 


06/23/81 06:49:28 JASADD1 02/09/81 
MENU SELECTION 1 


THIS SELECTION ADDS A CUSTOMER 
NAME AND ACCOUNT RECORDS. 


ACCOUNT NUMBER: ____ 
CUSTOMER NUMBER: 


ADDRESS (LINE 1): 
ADDRESS (LINE 2): 
CITY/STATE/ZIP: 
TELEPHONE NUMBER: > 


ENTER 'M' TO RETURN TO THE MENU: 
PLACE CURSOR HERE TO TRANSMIT -->[_] 





Figure 4-3. Output Generated by JAADD1 on First Pass 


96/23/81 06:49:28 JASADD2 02/09/84 
MENU SELECTION 1 
THIS SELECTION ADDS CUSTOMER 
NAME AND ACCOUNT RECORDS 
BRANCH NUMBER: 
SALESMAN NUMBER: 


PROJECT MANAGER: 
ACCOUNT CONTACT: 


DATES 
CONTRACT CONVERSION PROPOSED SYSTEM 
SIGNED STARTED COMPLETION INSTALLED 


| end | ff fod ee /_d 


PLACE CURSOR HERE TO TRANSMIT -->[_] 





Figure 4—4. Output Generated by JAADD1 on Second Pass 
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JAADD2 CODING 


13 


AOD NEW CUSTOMER (PART 2) 


ooool1H 

Onogo2Fe* 
OOO03Fs 
OOO04Fs 
oooosFre 
OOO06F* 
O0007F* 
OOOOSFs 
OcCoooFs 
OOO1OFs 
Ooo11Fs 


OOog13Fs 
OGOO14Fs 
OOO15Fs 
ONO16F* 
OQOOl17TFs 
OOO18F* 
OOO19F® 
OO020F* 
o0021Fs 
COOZ22Fa 
00023F* 
ON024Fs 
O002S5Fe 
OO026F* 
OOO27TFs 
O0O2S8Fs 
OO029F * 
OOO3OFPIB 
OCO31IFIM, 
OOO32FOMA 
GOO33FCDA 


oCO3s4FCyUSTMST 
OOO3SFXREF1 
OOO7%6FSYSCTL 


OOO37IPIB 
O00361 
ONOZ9IIMA 
oro4ol 
coo4ir 
o0042T 
OCO43T 
ONG44T 
ooo4ssI 
O9046T 
GOG47I 
oco4ser 
GI0497 
OOUSOICDA 


SPERRY UNIVAC OS/3 
IMS ACTION PROGRAMMING IN RPG HI 


THIS PROGRAM TS CALLED 8Y JAADDIe 
SCREEN FROM THE CDA PLUS ANY DATA 


ENTERED ON THE 
ENTEREO ON THIS SCREEN 


*JASADD]* 


69 
JAADD2 


IT TAKES THE DATA THAT WAS 


(*JAADD2*) AND ADDS A CUSTOMER MASTEP 


AND ACCOUNT CROSS REFERENCE RECORD. THE PROGRAM THEN CALLS 
THE MENU OVERLAY. 


amar 


a 
N 


256 
lg 
64 


Figure 4-5. Action Program JAADD2 (Part 1 of 4) 


PROGRAM INFORMATION BLOCK 


INPUT MESSAGE AREA 


CONTINUITY PATA AREA 
CUSTOMEP MASTER RECORD 


CUSTOMER MASTER RECORD (DELETED) 
ACCOUNT CROSS-REFERENCE RECORD 


SYSTEM CONTROL RECORD 


SYSTEM CONTROL RECORD (DELETED) 
WRITE CUSTOMER MASTER RECORD 


WRITE ACCOUNT CROSS-REFERENCE RECORD 
RETURN TO MENU AFTER ADDS 
GENERAL PURPOSE INDICATCR 
CUSTOMER NUMBER ALREADY EXISTS IN CUSTMST 
ACCOUNT CODF ALREADY EXISTS IN XREF! 
GENERAL ERROR INDICATOR 


- LOCAL USAGE 


SYSTEM CONTROL 2ECORD NOT FOUND 


144 
135 


40905 


148 

256R GAY 
152 SAI 
642 6AT 


4PIB 
*IMA 
*OMA 
*CDA 
oIse 
DISC 
CISC 


s 
s 
Ss 


S4MPRDATEL 


2001 MBRAN 
Z267IMSLSM 
51 IMPMGR 
86 IMCONT 
92GIMSIGN 
98 IMCONV 


13497 MCOMP 
LIGOIMINST 
LIodIMRFU 
117 IMXMIT 


4 COPS#D 





73 77 (80) 


AJAANDD?2 
MJAADD2 
*JAADD2 
*JAADD2 
*JAADD2 
mJAADND2 
*JAADD2 
= JAANO2 
*JAADD2 
*JAADD? 
mJAAND2 


JAADD2 
JAAND2 
JAADD? 
JAAND? 
JAAND? 
JAADD? 
JAADD? 
JAAND? 
JAADD? 
JAAND? 
JAAND? 
JAADD2? 
JAAND? 
JAAND? 
JAADD2 
JAADDZ 
JAAPD? 
JAAND? 
JAADD? 
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o00s2I 5 29 COMSEL JAAND? 
000531 % 8 6©350COCUST JAANDZ 
ooos41 36 39 COACCT JAANRD? 
ooo0ssti 4G 4OOCDPASS JAAND? 
oooser 4) 41 COSTAT JAAND2 
ooo5s7I 42 47 CDCPGM JAAND? 
QNOS8I* END OF STANDARD CDA FIELDS JAADD2 
ooosg9r 4&8 82 CDNAME JAAND? 
00060! 83 172 CNAORI JAAND2 
ooov6l1T 1N3 122 CCADR2 JAADND? 
000621 123 137 CDOCITY JAAND2 
000631 178 139 COSTE JAADD? 
oo064! P 149 1420cC02IP JAADD? 
ongés5r P 143 1449CDAREA JAAND2 
ooo066! P 145 148NCDPHON JAADD2 
ONOE7ICUSTMST NS G4 256NCD JAAND? 
go0068sI OR us : JAADD? 
Goosg! 9 14ACMCUST JAAD? 
GOO7OIXREF1 NS G6 JAAND? 
ono71T 1 6 XICUST JAAPD? 
Ooag72ISYSCTL NS GR 64NCO JAADD? 
ooo73I1 OR G9 JAADD? 
ong74aT 7 31 SCERR JAAND? 
aoo7sc PEAD PIB JAA0D? 
undo76c ScAD CDA JAANDD? 
ocg77C EXSR $CUST eDUPLICATE JAAND? 
uou7Tsc N64 GOTO ERROR eCUSTOMEP A? JAADNDZ 
oro79c EXSR $PuUT oND PMOUT JAAPO? 
oonagsoc ExSR $XREF1 eNOW X-REF JAADD? 
onogsic Nél FOTO EFROR JAADD? 
goo8s2c EXSR SPUT JAAND? 
anos3c SETON 63 eCALt MENU JAADD2 
onas4c GOTO RETURN JAADD? 
oroasc FREOP TAG JAAPD? 
ongosec SETON 89 JAADNDZ 
o008s7C EXSR SERROR oGET TEyT JAAND? 
OnGssc RETURN TAG JAAND? 
onos9c EXCPT JAAPD2 
ono90C« JAADD? 
GOO91C* DEFINE WOPK AZ-EAS JAADD? 
J0092C* JAADD? 
QNCI3CLENLR MOVE X*yct WPK? 2 JAAND? 
COCS4CLRANLR MOVE X*Q7e WwEKY 4 JAAND? 
COGC9SCLANLR MOVE X°4UT wRKS 5 Jaatd? 
OCGIOCLENLR MOVE X*4c?t BLNKS <So6 JAADD? 
UNCITCLFNLR MOVE X*FE? WeKSN 57 JAAPD? 
COUSBCLANLR MOVc X°F OR WRKEN 6% JAAND? 
GlC99Ce JAADD? 
OO1L1900C*® CHECK CUSTOMES MASTER + ACCCUNT X-REFERENCE FCR DUPLICATES JAAND? 
3Cinics JAAPD? 
GC192CSR TCUST eEeS? JAAND? 





Figure 4-5. Action Program JAADD2 (Part 2 of 4) 
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JAADD2 CODING 
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o01c3csRr 
OO1LO4CSRN6YU 
Go1oscseR 
CO106C* 
QOO10O7CSR 
oo0108csR 
OOLO9CSRN61 
YO110CSR 
00111C* 


cOCUST CHAINCUSTMST 
SETON 
ENDSR 


SXREF 1 BEGSR 

CDACCT CHAINXREF1 
SE TON 
ENOSR 


61 
a7 


O0112C# ADD CUSTOMER OR ACCOUNT CROSS-REFERENCE RECORDE 


0N113C# 
o0114CSP 
OO11SCSR 
00116CSR 
50117CSR 
OC118C#® 


LPUT REGSR 
EXCPT 
SETOF 
ENOSR 


00119C* GET ERROR MESSAGE FOR ERROR OVERLAY SCREEN 


00120C* 
OO121CSR 
GA122CSR 
OO123CSR 86 
VO1Z4CSR 87 
oo125CsRr 
00126CSR 
GO127CsR 
00128CSR 
001290 


O013G0* SOME FRPFOR HAS OCCURED - PUT OUT 


6013104 

O01320P 7B Fa 
991330 

001340 
GO1IS00MA a 
091360 


fEOROR BEGSR 
MOVEL*EM® 
MOVE *S6° 
MOVE °*n7?* 
MOVELWRKY 
CHAINSYSCTL 
MOVE X*GO26" 
ENDSP 


e9 


&9 


OC1370* OVERRIOF TEXT LENSTH 


001360 
001390 
ON1L4SCOCHRA 
001410 
091420 
oN1430 
OO1L44Cs 


CC1450*® ads CUSTCMER MASTER 


0°1460« 


OMTEXL 
NOUSCERR 
Rg 


OO1LS7OCUSTHST FADD 6) 


01480 
cG1490 
on1sce 
Ge1s10 
oris20 
uO1S30 


COACCT 
IMPRAN 
COCuUST 
CONAME 
CLACRi 
CGADF2 


wRKY 
WRK 
wWRKG 
WRKE 
9G 
OMTEXL 2 


ERROR OVERLAY SCREEN 


lu *JAMENU® 


11 ore 


KB "JAFERR® 


14 
66 


ay ene 
G1 X*F F's 
47 *JAAGDZ? 


+ X-REFERENCE RECORES 


Figure 4-5. Action Program JAADD2 (Part 3 of 4) 
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eTEXT LENGTH 


77 (80 


JAAND2 
JAANDD2 
JAADND? 
JAADD?2 
JAAND? 
JAADD2 
JAADD? 
JAADD? 
JAADD2 
JAADD? 
JAAND2 
JAADD? 
JAADD?2 
JAAND? 
JAAND? 
JAAND? 
JAADD? 
JAAND? 
JAADD? 
JAAND2 
JAAND? 
JAADD? 
JAADD? 
JAAND2 
JAADD? 
JAADD? 
JAADD? 
JAADD? 
JAAND? 
JPADD? 
JAADD2 
JAAND? 
JAADD? 
JAADD? 
JAAND? 
JAADD2 
JAAND? 
JAAND? 
JAAND? 
JA ADD? 
JAAND? 
JAAND? 
JAAND? 
JAAND? 
JAADD? 
JA AND? 
JAAND? 
JAAPD? 
JAACD? 
JAAD? 
JA APD? 
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JAADD2 CODING 








1 5 7 9 13 37 41 45 73 77__=(80) 


001540 cOCITy JAADD2 
001550. COSTE JAADD2 
001560 co2IP JAAND? 
001570 CDAREA JAADD2 
001580 CDOPHON JAADD? 
001590 IMCONT JAADD? 
001600 POSITION 151 UNUSED JAAND2 
001610 IMSLSM JAAND? 
001620 IMPMGR JAADD? 
001630 IMSIGN JAAND2 
001640 IMCONV JAADD?Z 
001650 IMCOMP JAAND2 
001660 IMINST JaaNDd2 
001670 IMRFU JAANDO 
001680 ENTITLEMENTS JAADD? 
G01690 WRKSN JAAND2 
001700 WRKSN JAADD2 
001710 WRKSN JAADD?2 
001720 WRKSN JAADD2 
001730 WRKSN JAANDD?2 
001740 WRKSN JAADND2 
001750 WRKSN JAAND?2 
001760 WRKSN JAADD2 
001770 WRKSN JAADD? 
001780 WRKSN JAADD? 
091790 WRKSN JAAND? 
G01800 WRKSN JAAND2 
G01810*% POSITIONS 277 - 251 UNUSED JAAND? 
001820 PBDATE JAADD2 
001830 z JAAND? 
ONLB4SOXFEFL EAOD 61 JAAND2 
un1850 coOCcuUST JAADD2 
001860 CDACCT JAAND? 
GNLET0s JAADD? 
SC1880*e RETURN TO THE MENU AFTER ADP JAAD? 
ON1890% JAAD? 
UNISOOPIE E 63 JAAND2 
0961910 5 *JAMENU® JAANDO? 
091920 Ls G3 JAADD? 
OFLIZOCDA JAADD? 
001940 mry® JAADD? 
601950 x*ure JAAND? 
691960 *JAADD2* JAAPD? 





Figure 4-5. Action Program JAADD2 (Part 4 of 4) 
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JAADD1 PROCESSING 


Processing for the 
first pass 


Processing for the 
second pass 


Designing IMS transactions 
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There are two passes through JAADD1. Let’s summarize what 
happens in each pass. 





1. Reads data saved by JAMENU. 
2. Reads the program information block for data. 


3. Calls screen format services to create the output message 
screen, JA$ADD1. 


4. Schedules itself as successor program. 





1. Reads data entered on the JA$ADD1 screen. 


2. Reads data saved by JAADD1 on the first pass through the 
program. 


3. Validates data entered on the JA$ADD1 = screen and 
diagnoses errors. 


4. Calls on screen format services to create the output 
message screen, JAS$ADD2. 


5. Schedules JAADD2 as successor program and passes data 
to it to do the actual adding of the customer and account 
records. 


Once again you see the same basic design that we saw in 
Section 3 - a series of action programs all handling input, 
processing, and generating output. Perhaps you've also noticed 
that the action programs we're discussing are designed to 
accomplish one or two fundamental activities. It’s better to link a 
series of action programs together to accomplish many small 
tasks than it is to try to incorporate all these tasks into a single 
program. 
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Objectives of IMS In most user environments IMS is chosen for its interactive 
capabilities and fast throughput. To maintain speed and a 
conversational atmosphere, design your action programs to 
perform clearly defined tasks and to yield appropriate and quick 
responses. 


You'll see that these goals of speed and _ conversational 
atmosphere are at the forefront in the design of all action 
programs presented in this manual. 
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CONTINUITY DATA AREA CODING 














4.4. USING THE CONTINUITY DATA AREA 


Now let's focus our attention on the new features of action 
programming that JAADD1 introduces (Figure 4-2). 


File Description Form (CDA) 


JAADD1 uses four interface areas. We've already shown you 
ways to define the program information block, input message 
area, and output message area in Section 2; and in Section 3, 
we demonstrated how these areas are used. The use of the 
continuity data area, however, is new. 


Purpose of continuity An action program defines a continuity data area in order to read 
data area and/or update data saved there by the predecessor program or 
to pass data itself to a successor program. JAADD1 uses the 











continuity data area to read data saved by JAMENU, to update 
it, and to pass the updated data to the successor program. 
Here is a description of how JAADD1 defines the continuity data 
area in order to use it in the ways we just described: 
Defining the continuity 
data area 
7-13 User name assigned to the continuity data area 
15-16 Update demand file. Since JAADD1 intends to read the continuity 
data area to get data passed by JAMENU and to update it, it 
must define it as an update demand file. There are many other 
ways to define the continuity data area depending on how you 
intend to use it. See 2.15 for a detailed discussion of the entries 
you can make in columns 15 and 16. 
19 Required entry 
24-27 This is the configured size of the continuity data area for 
JAADD1. JAADD1 can pass 148 characters of data to its 
successor program. An action program can increase the size of 
the continuity data area of the successor program by moving a 
new value into the field continuity-data-area-inc in the program 
information block at output time. See Section 2. 
40-46 Required entry whenever defining the continuity data area 
Input Form Coding (CDA) 
Seven fields contain As you would expect, the input form describes all input fields 


data passed by JAMENU referenced by JAADD1. Notice, however, that for the continuity 
data area there are seven defined fields. They contain data 
passed by JAMENU. 
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Data passed by JAMENU Table 4-1 lists the continuity data area fields passed by JAMENU 
to JAADD1 and their contents when JAADD1 begins processing. 


Table 4-1. JAADD1 Continuity Data Area 


CDA contents 












The transaction code _ that 


transaction. 


initiated the IMS 


The menu selection made by the terminal operator. 












When JAADD1 begins executing, this field contains 
only zeros. JAADD1 uses this field on the second 
pass through the program. 






When JAADD1 begins executing, this field contains 
only zeros. JAADD?1 uses this field on the second 
pass through the program. 






JAADD1 uses this field to determine which pass it is 
through the program. 








This field contains a zero when there is no error 
condition. 


This field contains the name of the current action 
program. 






Defining the program The input form also defines fields for the program information 
Poe block input block (PIB) and input message area (IMA). The two program 
teias 


information block fields defined correspond to transaction-date 
and time-of-day. For a complete listing of program information 
block fields, see Section 2. The fields defined for the input 
message area correspond to data entered on the JASADD1 
screen and enter the program on the second pass. 


Calculation Form (CDA) 


Using SENTRY to When JAADD1 begins processing, it calls upon subroutine 

read CDA $ENTRY. This subroutine reads the continuity data area. The 
continuity data area contains data saved by JAMENU. The 

Determining which pass purpose of reading the continuity data area first is to determine 

through JAADD1 whether it is the first or second pass through the program. This 
information is contained in the field CDPASS. On the basis of 
whether CDPASS contains a zero (first pass) or 1 (second pass), 
all processing is determined. 


Using the continuity data When CDPASS=0, indicator 70 is set on and 1 is moved to the 

area to control processing field CDPASS. When CDPASS= 1 initially, indicator 71 is set on. 
& Indicator 70 triggers processing for the first pass through the 
program. Indicator 71 triggers processing for the second pass. 
The continuity data area is not used again until output is done. 
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Updating the continuity 
data area at output 


Output Form (CDA) 


Table 4-2 summarizes how JAADD1 updates the continuity data 
area when output occurs. All data saved in the continuity data 
area is passed to the successor program. 


Table 4-2. Summary of JAADD1 Continuity Data Area Update at Output 





CDPASS=1 


CDSTAT=0 


CDCPGM=JAADD1 


CDPASS=0 


CDSTAT=0 
CDCPGM=JAADD1 
All fields between 


lines 195 and 207 
are written. 


CDPASS=0 





Pass 1 through JAADD1 is complete. 
No error condition occurred. 
Name of the current program 


Pass 2 through JAADD1 is complete. CDPASS 
is reinitialized to zero since all RPG Il action 
programs are serially reusable. 


No error condition occurred. 
Same as for indicator 70 


These fields contain the data entered on the 
JAS$ADD1 screen and validated on the second 
pass through JAADD1. Notice that the location 
of IMCUST and IMACCT correspond to CDCUST 
and CDACCT described on the input form. This 
data is used in the updating of the CUSTMST 
and XREF 1 files in program JAADD2. 


Indicator 79 signifies the operator entered M on 
the JA$ADD1 screen. This means the operator 
wants to return to the menu. Consequently, 
CDPASS must be reinitialized to zero. 
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© 4.5. USING INTERNAL SUBROUTINES 


We already briefly touched upon JAADD1’s use of internal 
subroutines when we_ discussed $ENTRY. Using _ internal 
subroutines is a common tool of most RPG Il programmers. It 
Avoid repetitious code avoids tedious repetition of code. Action programs code internal 
subroutines in the same way as other RPG Il programs. 


JAADD1 uses four internal subroutines in all. We discussed 
SENTRY, which reads the continuity data area and determines 
which pass it is through the program. The other three 
subroutines are $CUST, $ERROR, and $REFDT. Let's start with 
the last one first. 


Subroutine $REFDT 


Before talking about subroutine $REFDT, let's establish some 
necessary background information. In all the action programs 
we've discussed so far, we defined the program information 
block (PIB) as an update demand file on the file description form. 


Reading the program We did this to move’ values into successor-id and 
ee block for termination-indicator when doing output. Other than that, the 
programs didn’t use the program information block. JAADD1, 

@ however, does. That explains why the program information block 


is also defined on the input form. JAADD1 references the fields 
PBDATE and  PBTIME. These _ fields correspond to 
transaction-date (positions 49-54) and time-of-day (positions 
55-60) in the program information block. 


Defining program On lines 082-084 of Figure 4-2, JAADD1 reads the program 

information block size information block. This brings all program information block fields 
into the program. The reason all 7O positions of the program 
information block become available to JAADD1 is because they 
were defined on the file description form in record length. 


Executing $REFDT Now JAADD1 moves PBDATE to a field called WRK6N and 
executes subroutine $REFDT. 


Reformatting a field The purpose of this subroutine is to reformat transaction-date. Its 
present format in the program information block is yymmdd. The 
$REFDT subroutine moves the two leftmost characters (yy) in 
WRKE6N to WRK2 (a 2-position field). It then multiplies WRK6N 
(containing mmdd) by 100 producing a result field mmddOO. The 
$REFDT subroutine then moves WRK2N (containing yy) back to 
WRKEN. The result is a reformatted date, mmddyy. 
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PIB is useful 


Validating data 


Use screen formats or 
action program 


When data is invalid 


When errors occur 


Used to send error 
messages to terminal 
operator 


There is nothing particularly unique about this subroutine. The 
reason we presented it is to point out that there is much data in 
the program information block that action programs can put to 
very good use. This was simply one example. 


Subroutine $CUST 


The second internal subroutine $CUST validates the data entered 
on the JA$ADD1 screen. Due to the conversational nature of 
IMS, there is a continual exchange of data taking place betweeen 
IMS and the terminal. As a result, there must be a means for 
checking the validity of the data the action program receives. 
Screen format services provides a certain amount of validation of 
terminal operator entries. However, if you aren’t using screen 
format services or if your application requires special validation 
procedures, the action program must do it. JAADD1 uses the 
subroutine $CUST to do this. This subroutine executes only 
during the second pass through the program (when indicator 71 
is set on). 


First, the values entered (at the terminal) in fields IMCUST and 
IMACCT are compared to zeros. If they don’t contain zeros, the 
value IMCUST is checked against the index for user file 
CUSTMST, and the value IMACCT against the index for file 
XREF 1. If no key is found for either value, processing continues. 
Otherwise, if IMCUST or IMACCT are zeros or if a key already 
exists with the same value as IMCUST or IMACCT, then 
indicators 85,86, or 87 are set on accordingly. Each of these 
indicators in turn sets on indicator 89, the general error indicator. 


Subroutine $ERROR 


When indicator 89 is set on, before output takes place, a third 
internal subroutine takes control; it is $SERROR. Again, here is a 
little background information before discussing this subroutine. 


Notice that on the file description form (line O40) we defined a 
user file, SYSCTL. This MIRAM file contains a_ series of 
user-created error messages to be sent to the terminal operator 
at program termination when an error condition occurs. In this 
way, terminal operators are kept aware of the status of their 
requests. The internal subroutine, SERROR, uses the SYSCTL file. 
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@ 4.6. USING AN ERROR MESSAGE FILE 


Creating a user error file When indicator 89 is set on, $ERROR takes control. Depending 
on which specific error indicator is set on (85,86,87), RPG Il 
creates a key that is used to chain into the SYSCTL file. This file 
contains error messages related to specific errors that can occur 
during JAADD 1's processing cycle. 


Table 4-3 summarizes the error indicators that can be set on 
when JAADD1 is executing, the key that $ERROR creates, and 
the error message that goes to the terminal when the program 
terminates: 


Table 4-3. Summary of Error Indicator and Error Messages for JAADD1 


Error messages 




















generated aS SS 
CUSTOMER NUMBER ZERO AND/OR ACCOUNT CODE 
BLANK. PLEASE ENTER AGAIN. 
CUSTOMER NUMBER ALREADY EXISTS IN 
CUSTOMER MASTER FILE. PLEASE ENTER AGAIN. 
ACCOUNT CODE ALREADY EXISTS IN X-REFERENCE 
FILE. PLEASE ENTER AGAIN. 

Selecting error message As we mentioned earlier, indicators 85, 86, and 87 all set on 


indicator 89. When output is done for indicator 89 (general error 
indicator), the error message identified by the $ERROR subroutine 
(Table 4-3) is sent to the terminal. These messages make it easy 
for the terminal operator to see the cause of the error and to 
correct the mistake and try again. 
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4.7. USING SCREEN FORMAT SERVICES 


No DICE or FCCs required 


Coding needed to build 
screens 


Screen control 


Work area required 


We have now talked about using the continuity data area, 
internal subroutines, an error file, and displaying error messages 
at the terminal. That leaves one other feature of JAADD1 to 
discuss — using screen format services. 


You've probably noticed that the output coding for JAADD1 
contains none of the hexadecimal sequences so prevalent in 
RCMENU and RCCUST. JAADD71 formats all its output screens 
using screen format services. This is by far the easist way to 
format your output messages. The coding required is minimal. 


Lines 151-152, 166-167, 190-191 show the coding needed to 
build three different screens in the output message area. Which 
screen is built depends on which indicator is set on. When 
indicator 89 is set on, the error screen JA$ERR is built. When 
indicator 70 is set on, JA$ADD1 is built, and when indicator 71 
is set on, JA$SADD2 is built. Figures 4-3 and 4-4 show the 
screens JA$ADD1 and JASADD2. Figure 4-6 illustrates a typical 
error screen when indicator 89 is set on. 


06/23/81 


06:49:28 
MENU SELECTION 1 

THIS SELECTION ADDS A CUSTOMER 
NAME AND ACCOUNT RECORDS. 

ACCOUNT NUMBER: _ 

CUSTOMER NUMBER: 

NAME: 

ADDRESS (LINE 1): 

ADDRESS (LINE 2): 

CITY/STATE/ZIP: 

TELEPHONE NUMBER: 


JASADD1 02/09/81 


ENTER ‘M' TO RETURN TO THE MENU: 
PLACE CURSOR HERE TO TRANSMIT -->[(_] 
ACCOUNT CODE ALREADY EXISTS IN X-REFERENCE 
FILE. PLEASE ENTER AGAIN. 





Figure 4-6. Error Screen Generated for Program JAADD1 


To use screen format services, you must configure a work area, 
although you don't define a work area in your action program. 
The work area is specified in the ACTION section of the IMS 
configuration (WORKSIZE=n). 
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When an action program is ready to create a screen, RPG Il 

Moving variable fields moves all variable fields in the output message area to the work 

to work area area before it calls upon screen format services to generate the 
screen. The screen format generator then uses the output 
message area to build the entire output screen. When the screen 
is complete, the variable fields are returned to the output 
message area to await program termination. At that point, the 
entire contents of the output message area (screen and variable 
fields) are transmitted to the terminal. 


Coding for screen To use screen format services, you must enter on the output 
format services form: 


> aK in position 42; 


> the number of characters in the screen format name in 


position 43; and 
i 


ee 


> the format name beginning in position 45. 


When listing the variable fields to be output to the screen, 
Listing output fields in remember to list them in the order in which the screen format 
& ps ee screen generator is expecting them - that is, in the order they are 
defined in the screen format. Also, the first variable field cannot 
occupy a position before position 17. The first 16 positions 
always contain the output message area header. 


For a complete discussion of how action programs can use 
screen format services, see Section 6. 
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5. Special Types of Output Messages 


Sections 3 and 4 Sections 3 and 4 presented several examples of action programs 

(summarized) performing the fundamental processes of accepting input from 
the terminal, processing that input, and producing output. They 
showed convenient programming techniques for accomplishing 
these activities. After you've studied these examples, you should 
be able to write simple action programs. 


5.1. DIFFERENT TYPES OF OUTPUT MESSAGES 


In this section, we describe additional capabilities that IMS 
provides for generating output messages. As you become more 
experienced, you will find these capabilities very useful. They are 
the ability to: 


send uninterrupted output messages to a terminal or 


auxiliary device attached to the terminal (continuous output); 


multiple output messages; 





Types of output 





@ a transaction at a terminal other than the source 
‘terminal (output-for-input queueing); and 


4 messages to another terminal (message switching). 





5.2. GENERATING MULTIPLE OUTPUT MESSAGES 


Definition When an action program generates more than one output 
message, we call it multiple output. 


Example Program LSTLIM (Figure 5-1) demonstrates how an_ action 
program generates multiple output messages. 
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Multiple Output Message Program (LSTLIM) 
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What LSTLIM does LSTLIM sequentially processes an_ indexed file, STOCKS, 
containing stock records. The terminal operator enters as input 
low and high limit values that determine where processing of the 
file begins and ends. When LSTLIM receives these values, it 
begins reading STOCKS at the low limit and continues until the 
high limit is exceeded or the end of file is reached. When the 
program terminates, the records read are displayed at the 
terminal in groups of 10. 


Coding the File Description Form 


Lines 001-003 contain the file description form coding for the 
program. The operations performed are: 


File definition 










LSTLIM uses the input message area defined as the primary file, INPUT. 
LSTLIM also uses an input demand file, STOCKS. STOCKS is an indexed file 
containing 80-character records on disk. L in column 28 means the file is 
processed sequentially within limits. The 3-character key (columns 29-30) is 
alphanumeric (column 31) and begins in position 1 (column 35-38). 


LSTLIM uses the output message area defined as the output file, OUTPUT. 


Coding the File Extension Form 


Line 004 contains the file extension form coding for the program. 
The operation performed is: 


Array definition 







Array A, defined in column 27, holds the stock records processed. When full, 
the array contains ten 80-character records. 


Coding the Input Form 


Lines 005-010 contain the input form for coding the program. 
The operations performed are: 












Input field definition The LOWLIM field (positions 21-23 in the input message area) defines the 
lower limit used in processing the file, STOCKS. Positions 1-16 contain the 
input message area header; positions 17-19 contain the transaction code, 


STK; and positions 20 and 24 contain spaces. 








Operator entries The HGHLIM field (positions 25-27 in the input message area) defines the 
upper limit used in processing the file, STOCKS. When initiating the 
transaction, the operator enters the transaction code, the low limit, and the 
high limit. Since LOWLIM and HIGHLIM are the only input fields that LSTLIM 


references, they are the only ones defined on the input form. 


Key definition The STOCKS file contains 80-byte records that begin with a 3-byte key. 
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Coding the Calculations Form 


Lines 011-023 contain the calculations for the program. The 
operations performed are: 


Calculation form coding 


LSTLIM uses the input field LOWLIM to set the lower limit for processing the 
| file, STOCKS. 


The array index (!) is set to 1. 


The LOOP operation processes 10 STOCKS records before exception output 
is done. 


RPG Il begins reading STOCKS at the lower limit (LOWLIM). If end-of-file is 
reached, indicator 20 is set on and processing continues at line 022. 


If the end-of-file condition is not met, the field KEY is compared to HGHLIM 
to determine if the high limit for file processing was exceeded. If KEY is 
greater than HGHLIM, indicator 20 is set on and processing continues at line 
022. 


If the end-of-file condition doesn’t occur or high limit isn’t exceeded, the 
record is moved to array, ARY. 


The array index is incremented by 1. 


The array index is compared to 11. If | equals 11, the array contains 10 
records. Indicator 30 is set on. 








When indicator 30 is set on, exception output is done. The 10 elements in 
the array are moved to the output message area. However, this output 
message doesn’t go to the terminal until LSTLIM terminates. Once the 
contents of the array are moved to the output message area, the array is 
blanked out to allow it to receive another set of 10 records. 


After exception output is done, processing resumes at line 020 and the array 
index is reinitialized to 1. Record processing begins to create another array of 
data. 


When | is less than 11, indicator 30 is not set on. Processing returns to 
LOOP to read another record (line 013). This continues until the array is full, 
end-of-file condition is reached, or high limit is exceeded. 


When indicator 20 is set on by the end-of-file condition or by exceeding the 
high limit for file processing, the array index is compared to 1. If it is greater 
than 1, exception output occurs. 
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Coding the Output Form 


Lines 024-035 contain the output form coding for LSTLIM. The 
operations performed are: 

















Output form coding 


The output message area is OUTPUT. Exception output to the output 
message area occurs when the array contains 10 records (indicator 02 is set 
on) or when the array is partially full and indicator 20 is set on. 


The first output field is a 4-character device independent code (DICE) 

sequence ending in position 20. (The output message area header occupies 

_ the first 16 positions.) The DICE code sequence positions the cursor at line 2, 
position 1 on the terminal screen. 


Heading data is displayed. 
This DICE sequence repositions the cursor at line 3, position 1. 


The 800-character array (10 records, 80-characters each) is displayed using 
blank after. Blank after reinitializes all elements of the array to zeros or blanks. 
» This is needed because the array may be used many times during execution 
_ of the program depending on how many stock records are processed. When 
_ processing is complete, the array is again blanked out. This is needed 
because action programs are serially reusable. 


LSTLIM generates as As you can see, LSTLIM can generate as many output messages 

many messages as needed as needed. The low and high limits entered as input by the 
terminal operator are the sole determinants of the number of 
output messages - groups of 10 records each - that are 
generated. 


5.3. HOW MULTIPLE OUTPUT MESSAGES ARE PROCESSED 


The important point to remember regarding to multiple output 
messages, just as with any output message generated by an 
action program, is that none of the messages go to the terminal 
until the action program terminates. To understand what happens 
When messages between the time these output messages are generated and 
are transmitted when they actually appear on the terminal screen, let's use the 
action program LSTLIM once again and supply input data. 





The input message entered is: 


Terminal input STK is the transaction code. It identifies 
to IMS the’ program LSTLIM _ that 
processes this transaction. The entries 
EEC and MAN define the lower and 
upper limits respectively, for processing 
the file, STOCKS. 
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Let's assume that there are 27 records 
in STOCKS that fall between these 
limits. The first time LSTLIM does 
exception output, the 10 records 
processed are moved from the array to 
the output message area. Each time 
exception output is complete, the array 
is blanked. 


When control returns to the program, 
the program reinitializes the array index 
to 1 and processes 10 more records. 
Indicator 30 is set on, signaling more 
exception output. 


When the second request to do 
exception output is received and the 
output message area already contains 
data, RPG Il issues a SEND function call. 
IMS takes the contents of the output 
message area and moves it to an ICAM 
(communications) queue. Note that the 
first set of 10 records was not sent to 
the terminal. The output message area 
is now free to receive the exception 
output. The second set of 10 records in 
the array is now moved to the output 
message area. 


Up to now, 20 records were processed. 
LSTLIM generated two output 
messages, neither of which was sent to 
the terminal. The second message is in 
the output message area; the first, in an 
ICAM queue. 


Once again your program reads 
STOCKS. After seven additional records 
are processed, indicator 20 is set on. 
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The high limit for file processing has 
been exceeded. The array index is 
compared to 1. It is 8. This signals 
more exception output. Again RPG Ill 
checks the output message area. It 
contains data. The SEND function call is 
repeated and the contents of the output 
message area (the second set of 10 
records) is moved to the ICAM queue 
where the first set of 10 records is 
waiting. Now the output message area 
receives the seven records in the array. 


At this point, processing is complete. 
When the action program terminates, 
RPG Il issues a call to the IMS RETURN 
function. IMS moves the iast output 
message (the seven records) to the 
ICAM queue and begins transmitting 
output to the terminal. 


The data is sent to the terminal in the 
order that LSTLIM generated it - that is, 
the first screen of 10 records, the 
second screen of 10 records, and 
finally, the third screen of 7 records. 


After the first screen is transmitted, the 
message waiting light alerts the terminal 
operator that there is more output. 
When ready, the operator acknowledges 
the signal by pressing the MSG WAIT 
key and the next screen of 10 records 
is sent to the terminal. This process 
continues until all output generated by 
the program is sent to the terminal. The 
transmission of each output message 
after the first is preceded by the 
message waiting light and the operator 
pressing the MSG WAIT key. 





MULTIPLE OUTPUT MESSAGES 
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MULTIPLE OUTPUT MESSAGES 


Message handling manner just described. All output 








Whenever the action program creates 


more than one output message - using ee 


exception, detail, or total time output - 
RPG Il and IMS handle the output in the 


messages, except the final one, are 
transmitted using the SEND function. 
The last output message is always 
. transmitted using a RETURN function 
when the program terminates. 





Operator responses to Table 5-1 shows how the terminal operator is informed of 
multiple output multiple output and how the operator acknowledges that output. 


Table 5-1. Indicating and Accepting Multiple Output Messages 












Display (except IBM 3270) | Message waiting light 


/CMW or other 4-character message” 


Message waiting light or /CMW* 


Press message waiting key. 









Hard copy (except 
DCT 1000} 


Press CTRL/G, then press CTRL/C. 







IBM 3270 Press PA1 key. 


DCT 1000 


Message waiting light Press CTRL/G, then XMIT. 


"This message is defined by the MSGWAIT operand of the TERM macro in the ICAM network definition. 
The default is /CMW. 


Requirement when using lf the action programs you write use the SEND function, you 


SEND function 


Disk queueing 


must specify the UNSOL=YES parameter in the OPTIONS section 
of the IMS configuration. If the SEND function is used frequently, 
you should also include disk queueing for output messages when 
defining your communications network (ICAM). When you specify 


Message queueing disk queueing, IMS queues output messages generated by an 


action program on disk each time the SEND function occurs. 
These messages are sent to the terminal when the program 
terminates. Disk queueing allows for more productive use of main 
storage. 


Multiple output If you want to examine each screen of data containing output, 


message limitations 


issuing multiple output messages is a good idea. You should not 
use it, however, as a substitute for obtaining lengthy output 
messages because the operator wastes considerable time 
pressing the MSG WAIT key to obtain the entire output. 
Instead, use the continuous output feature discussed in 5.4 
through 5.12. 
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5.4. GENERATING CONTINUOUS OUTPUT 


Definition The second capability involving output messages is the ability to 
transmit a series of output messages to a terminal or more 
commonly to an auxiliary device attached to the terminal without 
operator intervention. This is called continuous output. 


Useful for lengthy reports This capability is very useful when you want to print lengthy 
reports at an interactive terminal. 


Specifying continuous To use continuous output, you must specify CONTOUT=YES in 


output in IMS the OPTIONS section of your IMS configuration. 
configuration 


5.5. DEVICES THAT CAN RECEIVE CONTINUOUS OUTPUT 


Terminals and auxiliary Action programs can direct continuous output to hard copy 

devices supported terminals or to auxiliary devices (printer, tape cassette, or 
diskette) at display terminals. For a complete list of terminals and 
auxiliary devices supported by IMS, see the IMS system support 
functions user guide, UP-8364 (current version). 


5.6. CODING FOR CONTINUOUS OUTPUT 


Specifying continuous To distinguish a continuous output message from other output 

output in program messages, an action program moves a special value to the 
aux-function field (position 15) of the output message area 
header. You move this value at the same time as you generate 
your output message. When the program terminates, IMS checks 
this field and recognizes that the message generated is a 
continuous output message. 


Specifying continuous If that message is to go to an auxiliary device, as opposed to 
bovis to auxiliary just going to the display terminal, the program also moves a 
evices 


value to the aux-device-no field (position 16) of the output 
message area header when generating the output message. This 
value informs IMS which device receives the continuous output 
message. You assign a unique number to each auxiliary device 
when you define your communications network. 


Aux-function field settings Table 5-2 summarizes the settings for the aux-function field 
when transmitting continuous output to a terminal or to an 


auxiliary device. You find those values in columns 6 and 7 of 
Table 5-2. 
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Table 5-2. Settings for Aux-Function Field of the Output Message 
Header (Print/Transfer Options) 






X Print Mode 
Print Transparent 


rim fom EW kd 
ee 
mea fx | 
a ae 





Transter All (ESC G X eee 

Transter Variable Xx 

(ESC F) 

Transfer Changed X 
(ESC E) 






Directing Continuous Output to a Terminal 


Looking at the columns labeled Continuous Output in Table 5-2, 
you notice that if you're sending continuous output to the 
terminal (primary device), you move the character C or a 
hexadecimal C3 to the aux-function field. Figure 5-2 shows how 
you code the output form to send continuous output to the 
terminal. 





STACKER SELECT: 


€ FETCH OVERFLOW OUTPUT INDICATORS 


[oars ronmar] CODES FRO 

DATA FORMAT ~_e00: a POS ie: 

NEGATIVE VALUE INDICATION | sycemten | BALANC 
one TO PRINT 


END + ~ ves 
POSITION 
IN 
vuteu? 
WECOML 





TYPE HDT E PeLA 
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CONSTANT OR EOIT WORD 


ZB BLANK ArTEN 


au as 





lau Pate Naat ae 
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Figure 5-2. Coding a Continuous Output Message for the Terminal 
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© Directing Continuous Output to an Auxiliary Device 
Continuous output for When you are transmitting continuous output to a COP, TP, 
an auxiliary device cassette, or diskette auxiliary device, Table 5-2 illustrates that 


there are numerous values you can move to the aux-function 
field. The value you choose depends on the print or transfer 
option you want. 


Print and transfer options Table 5-2 lists the print and transfer options you can select and 
their corresponding values. Table 5-3 further defines these 
options. 


These print and transfer options can be used to transmit 
messages to auxiliary devices whether or not you're using the 
continuous output feature. Also, some auxiliary functions aren't 
allowed if you use screen format services. See Table 6-2. 


Table 5-3. Print and Transfer Options 





Print Mode Message transmitted has the same format as the terminal 
@ screen. Cursor return sequences for the screen apply. 

Print Transparent Message transmitted is independent of the terminal screen 
format. Whatever format you include with your message 
applies. 

Print Form (ESC H) Message transmitted contains all unprotected characters 


from the start-of-entry (SOE or home position) to the cursor. 
Field control characters are suppressed. 


Transfer All (ESC G) Message transmitted to the auxiliary device contains all 
characters from the start-of-entry character to the cursor 
including field control character sequences. 


Transfer Variable (ESC F) Message transmitted to the auxiliary device contains only 
the unprotected characters between the start-of-entry 
character and the cursor including field control character 
sequences. 


Transfer Changed (ESC E) Message transmitted to the auxiliary device contains only 
the changed characters between the start-of-entry and the 
cursor including FCC sequences. — 
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Definition of print mode 
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Identifying the auxiliary 
device 
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One of the more commonly used options is print-transparent 
mode. In this mode, although the continuous output message 
generated goes through the logic of the primary device, its 
format is independent of the terminal screen format. Only device 
independent code (DICE) sequences and field control characters 
(FCCs) you use to format the continuous output message apply. 
The cursor return characters normally inserted by the terminal are 
not transmitted. Thus, the length of the lines written to the 
auxiliary device is independent of the line length of the screen. 


When using print-transparent mode with a UNISCOPE 100 
display terminal, make sure that the output message generated 
doesn't exceed screen capacity. If it does, the excess lines wrap 
around and overlay the first few lines. Since the message on the 
screen is the message sent to the auxiliary device, the 
transmitted result is a message beginning with the excess lines 
instead of the original lines. The same consideration applies to all 
display terminals; however, the larger screen capacity of most 
terminals makes wraparound less likely. 


In print mode, the continuous output message transmitted to the 
auxiliary device has the same format as the screen - that is, 
cursor return characters apply. For further details on print-mode 
and print-transparent mode, refer to the UNISCOPE programmer 
reference, UP-7807 (current version), and the UTS 400 
programmer reference, UP-8359 (current version). 


When you choose either print or transfer options, you can allow 
or inhibit space suppression (see Table 5-2). When you specify 
allow space suppression, the remote device handler suppresses 
all nonsignificant spaces in the output message. When you 
specify inhibit space suppression, the remote device handler 
changes all spaces to DC3 characters making it necessary to 
strap the printer to space when it receives a DC3 character in the 
output message text. 


As we already noted, when you're transmitting continuous output 
to an auxiliary device, you must also move a value to the 
aux-device-no field. The value you move to the aux-device-no 
field identifies that auxiliary device. Each auxiliary device attached 


to a terminal has aé_= specific number as defined in the 
communications network definition. 
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Example Let's assume you want to transmit continuous output to a 
cassette using the transfer-all option. You would specify 
hexadecimal C2 or the character B in the aux-function field. In 
aux-device-no, you would put the value configured for the 
auxiliary device to which you are directing continuous output. 
Figure 5-3 shows how the coding might look: 


DATA FORMAT 
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Figure 5-3. Coding a Continuous Output Message for an Auxiliary Device with the 
Transfer-All Option 


5.7. WRITING A CONTINUOUS OUTPUT PROGRAM 


You write an action program to generate continuous output as 
you would any action program. However, there are some special 
and very important considerations to take into account. 


Using the aux-function First, as we described in 5.6, if you’re transmitting continuous 

field output to the terminal, on the output specifications form you 
must move hexadecimal C3 or the character C to _ the 
aux-function field (position 15) of the output message area 
header (see Figure 5-2). This informs IMS at action program 
termination that this program generated a continuous output 
message. It is not very common to direct continuous output to a 
terminal exclusively. 
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If you're transmitting the continuous output message to an 
auxiliary device attached to the terminal, you move a value to the 
aux-function field specifying the print or transfer option you 
select. Table 5-2 summarizes these options. In addition, you 
enter in the aux-device-no field (position 16) of the output 
message area header, the number configured for the auxiliary 
device. To illustrate these procedures, Figure 5-4 shows the 
output form coding to generate continuous output to a printer 
using the print transparent option with inhibit space suppression 
when the program terminates. 


CODES 


COMMAS: ze 
WEGATIVE VALUE INDICATION] wwgeareD | ALM 











CONSTANT OR EDIT WORD 





gy ey 








Figure 5-4. Coding a Continuous Output Message for a Printer with Print 
Transparent and Inhibit Space Suppression 


Second and most important, an action program can generate only 
one continuous output message. This message can be as large 
as the screen capacity of the terminal receiving the message will 
allow. Of course, this varies depending on the type of terminal or 
workstation you're using. Whether the message is destined for 
the terminal or for an auxiliary device, it always passes through 
the terminal screen first. If the message is larger than the screen, 
it wraps around, and when transmitted to the auxiliary device, 
the beginning of the message is lost. Consequently, the size 
restrictions for the terminal also apply to transmitting continuous 
output to an auxiliary device. 


The term continuous output, by its very nature, suggests lengthy 
output messages. If an action program can produce only one 
continuous output message and the largest message can only be 
the size of a screen, you're undoubtedly wondering how we 
generate long messages. 
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That brings us to the third point: to continue generating 
continuous output, an action program must name a successor. 


The key is that the first program generates its continuous output 
message and names a successor program to continue generating 
continuous output. That program, in turn, names a successor and 
so on, and so forth. One program could reschedule itself 
numerous times or the successor program could be a different 
program. 


Once you identify an output message to IMS as _ continuous 
output, the message is transmitted to the terminal or auxiliary 
device and the successor program is scheduled to continue 
generating continuous output. There is no need for operator 
intervention. This is how lengthy reports can be printed at an 
interactive terminal. 


To name a successor, the action program moves the successor’s 
name to the successor-id field (positions 5-10) of the program 
information block when the program terminates. This is the same 
procedure any action program follows for naming a successor. 


The fourth consideration is that the action program must also 
move an E (for external succession) to the termination-indicator 
field (position 11) of the program information block when the 
program terminates in order to continue generating continuous 
output. 


The reason for specifying external succession (E) as opposed to 
other types of termination is that when continuous output takes 
place, IMS generates a 5-character message that is sent as input 
to the successor program. This program must be prepared to 
accept that input. External succession means that the successor 
action program is ready to accept an input message. 


The fifth and final point to remember when generating continuous 
output is that this message must be the final message the action 
program creates - that is, it must be transmitted using the IMS 
RETURN function when the action program terminates. You can't 
use the SEND function to transmit a continuous output message. 


This does not mean, however, that an action program generating 
continuous output is restricted from using the SEND function 
altogether. The program can generate as many output messages 
as it chooses prior to creating the continuous output message. 
All the prior messages are transmitted using the SEND function. 
However, the continuous output message must be the last 
message generated and consequently, transmitted using the 
RETURN function. 
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Summary 
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You recall that when an action program generates multiple output 
messages, all the messages except the last are transmitted using 
the SEND function. The last output message generated by an 
action program is always transmitted as a RETURN function. For 
more detailed information on how output messages are handled, 
see 5.3. 





> An action program execution can generate one continuous 
output message only. 


> The continuous output message can’t exceed screen size. 


> To continue generating continuous output, you specify a 
successor program and external succession. 


> The continuous output message must be the final message 
the program generates. 
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® 5.8. THE IMS DELIVERY CODE 


Identifies input message | \Whenever an action program generates a continuous output 
message, its successor program receives from IMS a 5-character 
input message. The first four characters contain the value placed 
in the continuous-output-code field (positions 9-12) of the output 
message area header by the previous program. Placing a value in 
this field is optional. Generally, this code identifies the previous 
program in some way. If the program doesn’t move a value to 
this field, then it contains binary zeros. 


Defining the delivery code The fifth character of the input message is the important one. It 
is a delivery code. The delivery code indicates whether ICAM 
successfully delivered the continuous output message to its 
destination or not. 


Indicating a value in Figure 5-5 shows how you code to move a value to the 
Sia hs Nac ta continuous-output-code field, and Figure 5-6 demonstrates how 
-code fie 


IMS returns this value and the delivery code to the successor 
action program. 


& STACKER SELECT/ 


F+FETCH OVERFLOW 








CONSTANT OR EOIT WORD 


fore Was Ye) ca ca ey ae 
i ’ 
(OKC ee reer on er a 


.ae 
Mera i teri aii iid 

















‘al 
abe Le a 








te] 
o 
: 


radr atari iQuT Por! 
teraalira MESSAG 
reooeliars MEKTI 














! 
a 
a 
: 
i 
| 








Figure 5-5. Coding to Move a Value to Continuous-Output-Code 
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Figure 5-6. Input Message Returned to Successor Program in Continuous Output 
Transaction 


How continuous-output-code Figure 5-5 shows that the value moved to 


field is used 


Specifying continuous 
output for auxiliary 
devices 


Continuous output status 


Continuous output 
status codes 


continuous-output-code is ECC1. ECC1 identifies the program 
generating the message. When the action program terminates, 
the continuous output message generated is transmitted. When it 
is received and acknowledged by the destination terminal, IMS 
schedules the successor action program and the value ECC1 plus 
the delivery code acknowledgment from ICAM are sent as input 
to the successor program. The value ECC1 comes into the 
successor program in the input message area in positions 17-20. 
The delivery code comes into the program in position 21. 


The other two output fields coded in Figure 5-5, aux-function 
and aux-device-no, respectively, indicate that the continuous 
output message generated by this action program went to an 
auxiliary device attached to the terminal. The message is sent 
using print-mode with space suppression. The configured number 
for the auxiliary device is 3. 


Obviously, the fifth character of the input message is the one of 
particular interest to the successor action program. It contains a 
value indicating the status of the continuous output message sent 
by the predecessor program. If the continuous output message 
was successfully delivered, the hexadecimal value 81 is returned 
to the successor action program. If the lowercase-to-uppercase 
translation option was specified for this action program at IMS 
configuration, the value 81 is translated to the character A. Any 
other value returned in the fifth character of the input message 
indicates the continuous output message was not successfully 
delivered. Tables 5-4 and 5-5 summarize the output delivery 
notice status codes that can be returned to an action program. 
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Table 5-4. Output Delivery Notice Status Codes Returned by IMS 





Successful output 
completion 


Line down or 
disconnected. 
Message deleted 
by IMS. 


Terminal 

marked down. 
Message deleted 
by IMS.@ 


Auxiliary 

device down. 
Message deleted 
by IMS. 

Output may be 
addressed to the 
primary device. 


Missing or 


invalid destination 


or auxiliary 
specification 
in header 


No ICAM 
network buffer 
available 
Disk error 
Invalid output 


buffer length 


NOTES: 


Yes Yes 


Yes Yes 


| i 


Yes Yes 
Yes Yes 
Yes Yes 
Yes Yes 


Yes, 


regardless 
of delivery 


Yes 


af | 


Yes 


Yes 


Yes 












11 


12 


34 


85© 


36 
370 


® The hexadecimal value 81, indicating successful output completion, is translated to 
the character A if the lowercase-to-uppercase translate option is specified for 
messages input to the successor action. Similarly, the hexadecimal values 84 
through 87, indicating error conditions, are translated to the characters D through G 
if the translate option is specified. 


output message. 


@ When a terminal is marked down, input solicitation (polling) by ICAM continues 
automatically. When ICAM receives input from the down terminal, that terminal is 
marked up and the input is scheduled for IMS. 

@® If this condition exists, a user action program can try to re-send the last continuous 
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Ready (good) status 
but COP/TP write 
function inoperative 


Device out of paper, 
inoperative, or in 
test mode 


Data error on TCS 


Device is not 
responding; it may 

be disconnected, or 

a read of unwritten 

tape may have occurred. 
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Table 5-5. UNISCOPE and UTS Auxiliary Device Condition Codes 
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44 
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5.9. RECOVERY CONSIDERATIONS WITH CONTINUOUS OUTPUT 


Recovery and restart action Recovery and restart processing are the responsibility of your 


program responsibilities 


Operator reinitiates 
output after error 
correction 


Program or operator 
can control output 


Function keys 


Terminal type affects 
recovery 


Polled device 
acknowledgment 


Nonpolled device 
acknowledgment 





action program. When the successor action program receives an 
unsuccessful delivery notice, it can continue’ processing 
continuous output or terminate the transaction. When the 
successor program continues processing, it can send a regular 
output message to the terminal requesting assistance and then 
terminate with external succession. Note that when a continuous 
output message is unsuccessfully sent to an auxiliary device, only 
that device is marked down. You can still send output to the 
primary device. 


After the error condition is corrected, the terminal operator can 
send an input message to the successor program to reinitiate the 
continuous output transaction. In this case, the successor 
program must be prepared to accept input from the terminal 
when necessary, as well as the delivery notice returned by IMS. 
You should consider this possiblity when designing your action 
programs. 


Both operator-entered input and delivery notice input can cause 
attempts to schedule the successor continuous output program. 
If operator-entered input exists, IMS processes that input and 
discards the delivery notice. You should, therefore, code your 
action program to handle keyboard input that can_ end, 
temporarily break, and resume a continuous output transaction. 
The best way to interrupt continuous output is to use function 
keys as keyboard input. Function keys are faster to use because 
they are never locked. 


When a delivery attempt is unsuccessful, there are a number of 
recovery options. In planning recovery, however, it’s important to 
realize the difference between polled and nonpolled devices with 
respect to unsuccessful delivery notices. 


The DCT 1000, UNISCOPE 100 and 200, and UTS terminals are 
polled devices and transmit an acknowledgment to ICAM after 
receiving a continuous output message; the nonpolled devices, 
TELETYPE* and DCT 500 terminals, do not. For nonpolled 
devices, a delivery notice is automatically generated; it always 
indicates successful delivery regardless of whether or not the 
output message was successfully delivered. Only a line-down 
condition returns an unsuccessful delivery notice. 


*Trademark of Teletype Corporation 
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Problem caused by 
nonpolled devices 
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not related to 
terminal type 


Consequently, IMS almost always receives a_ successful 
completion status from ICAM when a message is delivered to a 
nonpolled device. IMS sends this delivery code to the successor 
action program which, in turn, generates more continuous output. 
As you can see, this is a situation to be avoided. So, in critical 
parts of continuous output applications, avoid using nonpolled 
devices. 


Certain error conditions (the last four entries in Table 5—4) are 
detected by ICAM before the message is sent to the terminal. 
These errors return an unsuccessful delivery notice regardless of 
the device type. 
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5.10. A SAMPLE CONTINUOUS OUTPUT PROGRAM 


Example So far we have presented a great deal of information concerning 
continuous output. Now let’s look at an action program that 
generates continuous output. The program we will use is the 
second in a series of three action programs that make up a 
continuous output transaction. Let’s begin by. 
the first program, SALES 1, does: 





What SALES1 does m Updates a file, SLSST 


m Saves data used in updating the file in the continuity data 
area 


m Generates a continuous output message giving branch sales 
data 


m Names a= successor program to continue generating 
continuous output 


| Terminates with external succession 


The successor program is SALES2. Figure 5-7 contains the 
& coding for SALES2. The SALES2 successor program: 


What SALES2 does m receives the 5-character input message generated by IMS; 


m interrogates the fifth character of this message (delivery 
code); 


™ generates a continuous output message; 
™ names a successor program; and 


= terminates with external succession. 
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Figure 5-7. Continuous Output Program SALES2 
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Continuity data area On the file description form coding, notice that there are four 
interface areas. These should be very familiar to you by now. 
The continuity data area contains data passed by SALES1, the 
predecessor action program. This is the data that SALES2 will 
use to generate its continuous output message when the 
program terminates. You recall that an action can generate only 
one continuous output message and that message cannot be 

Interaction between larger than the terminal screen size. SALES1 generated one 

SALES1 and SALES2 continuous output message; but there is still more data to 
transmit. So, it scheduled SALES2 as successor to continue 
generating continuous output. 





This form defines input fields. Notice there are several fields 
defined for the continuity data area. These fields contain data 
passed by SALES1. 


In addition, there is one field defined for the input message area, 
Describing the delivery code DELV. DELV contains the delivery code returned by IMS. 
& Whenever an action program generates continuous output (in this 
case the first program in the transaction, SALES1), IMS returns a 
5-character code as input to the successor program. The fifth 
Successful completion character or delivery code indicates whether the first continuous 
output was successfully delivered or not. Every successor 
program in a continuous output transaction must be prepared to 
receive this code. 


In our example, the first four characters of the input message 
returned by IMS are SLS1 - the value moved to _ the 
Continuous-output-code continuous-output-code field (positions 9-12) of the output 
field message area header by action program SALES1. This value 
comes into the input message area of SALES2 in positions 
IMA header 17-20. The input message area header occupies positions 1-16. 
The action program, SALES2, doesn’t define positions 1-20 
because these fields are not referenced in the program. However, 
Delivery code position it does define position 21 since this position contains the delivery 
code generated by IMS, indicating whether the continuous output 
message created by SALES1 was successfully delivered or not. 
Before SALES2 generates a continuous output message of its 
own, it must determine if the first message was transmitted 
successfully. It does this by interrogating the delivery code. - 
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Interrogating the delivery 
code 


Unsuccessful delivery/ 
printer off 


Unsuccessul delivery/ 
printer out of paper 


Effect of printer 
inoperative delivery 
codes 


Request for operator 
intervention 





On the calculation form, the three COMPARE operations 
interrogate the delivery code to determine what processing 
occurs next. When DELV equals hexadecimal 81, the first 
continuous output message was successfully delivered. When 
this value is returned to the program, indicator 20 is set on and 
SALES2 generates continuous output. 


When DELV equals hexadecimal 41, the first continuous output 
message was not successfully delivered because the printer was 
not turned on. When this value is returned to the program, RPG Il 
sets on indicator 30 and SALES2 does not generate continuous 
output. 


When DELV equals hexadecimal 42, once again the first 
continuous output messsage was not successfully delivered 
because the printer was out of paper. When this value is 
returned to the program, indicator 40 is set on and SALES2 does 
not generate a continuous output message. 


To reiterate, when DELV equals hexadecimal 41 or 42, SALES2 
does not generate continuous output since the initial continuous 
output message generated by SALES1 was not successfully 
delivered. Instead, SALES2 calls SALES1 as its successor 
program to attempt retransmitting the first continuous output 
message. You'll recall that the values 81, 41 and 42 were 
described in Tables 5-4 and 5-5. 





In addition, when the delivery code indicates an unsuccessful 
attempt to deliver the first continuous output message, SALES2 
generates a regular output message (not continuous output) that 
is sent to the terminal operator. When indicator 40 is set on, the 
message sent is: RESET PAPER TO HOME. When indicator 30 is 
set on, the message sent is: TURN PRINTER ON. By doing this, 
SALES2 instructs the terminal operator to correct the situation 
that prevented the initial transmission of SALES1’s continuous 
output message. 
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Continuous output message When indicator O3 is set on, (SALES 1's continuous output 

generation message was successfully delivered) and SALES2 generates a 
continuous output message of its own. This message is 
transmitted as a CALL RETURN when the program terminates. 


Naming a successor program SALES2 specifies its successor program, SALES3, by moving 
that name to the successor-id field (positions 5-10) of the 
program information block. SALES3, which is not presented in 
this manual, is designed similar to SALES2 and continues 
generating continuous output. 


Passing the continuous In addition, when indicator 10 is set on, RPG Il moves the 

output code continuous output code SLS2 to positions 9-12 of the output 
message area header. This code is transmitted as input by IMS 
to the successor program (SALES3) in positions 17-20 of the 
input message area, along with the delivery code _ indicating 
whether SALES2’s continuous output message was successfully 
delivered or not. 


Print mode specification The number 3 in position 15 (aux-function field) of the output 
message area indicates that this output message is transmitted 
as continuous output using the print-mode option. Print-mode 
means that the output message takes on the same format as the 
terminal screen, that is, cursor return characters for the screen 


apply. 
Auxiliary device The number 1 in position 16 (aux-device-no) of the output 
specification message area indicates the continuous output is sent to an 


auxiliary device attached to the terminal. In our example, that 
device is a COP printer. The number 1 identifies the device as it 
was defined in the communications network definition. 


Termination When SALES2 terminates with external succession (E in the 
termination-indicator field), the continuous output message is 
transmitted to the terminal. It is transmitted as a CALL RETURN 
by IMS. 


Output to the printer Figure 5-8 shows the continuous output message generated by 
SALES2 as it appears on the terminal screen before being 
transmitted to the printer. 
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6/26/81 


1. CENTER CITY SUPPLY CO. :: 
5, 3572 FRANKLIN DRIVE 
+: MONROE, NH 72480 


BRANCH: 7531 
WASHINGTON LANE 
CUPERTINO CA 37121 


INVOICE: 362418 
DELIVERY DATE: 7/31/81 
SALES REPRESENTATIVE: GRACE A. MICHELLI 





Figure 5-8. Continuous Output Generated for SALES2 


Terminal screen size You may have noticed that the continuous output message 

limits message size generated by SALES2 is rather small. The reason for this is that 
the installation implementing this application program uses 
UNISCOPE 100 display terminals. Their relatively small screen 
size demanded small messages. In the following action program, 
you'll notice the continuous output messages generated are much 
longer. The installation using this application uses UNISCOPE 200 
display terminals. 
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® 5.11. ANOTHER SAMPLE CONTINUOUS OUTPUT PROGRAM 


Example 


UNIVAC OS/3 RPGIT VERS 781109 


The second example of a continuous output program is NCSC. It 
is quite lengthy; but its design is very similar to the program 
SALES2 described in 5.10. For that reason, we will point out 
only the new coding features it introduces. The coding for NCSC 


is in Figure 5-9. 
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Figure 5-9. Continuous Output Program NCSC (Part 1 of 9) 
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Figure 5-9. Continuous Output Program NCSC (Part 2 of 9) 
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Figure 5-9. Continuous Output Program NCSC (Part 3 of 9) 
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Figure 5-9. Continuous Output Program NCSC (Part 4 of 9) 
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Figure 5-9. Continuous Output Program NCSC (Part 5 of 9) 
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Figure 5-9. Continuous Output Program NCSC (Part 9 of 9) 


UP-9206 





SPERRY UNIVAC OS/3 5-38 
IMS ACTION PROGRAMMING IN RPG II 





CONTINUOUS OUTPUT PROGRAM NCSC 


Output message returned 
by unsuccessful delivery 


Issues error message 
to operator 


Different continuous 
output messages 


Saving the key of 
next record 


Receiving control from 
previous action program 





Lines 223-237 of Figure 5-9 show the output message that 
action program NCSC generates when the delivery notice 
returned to the program indicates that the previous continuous 
Output message was not successfully delivered. Notice that this 
message instructs the terminal operator to examine the printer 
for what could be causing the difficulty. 


Also notice that NCSC generates two different continuous output 
messages - lines 238-280 and 281-467 - depending on which 
indicators are set on or off, and that the continuous output 
messages created are quite lengthy. The only limitation on the 
size of the message is the screen size of the primary device to 
which the auxiliary is attached. These messages are being 
transmitted to a UNISCOPE 200 display terminal. 


Note that the program uses the continuity data area to save the 
key of the next record to be processed (line 474) when the 
program succeeds to itself (line 480). This is a particularly useful 
tool when the continuous output being generated is producing a 
report that prints the contents of an entire file. When the 
successor program is scheduled, it reads the continuity data area. 
It then does a SETLL using the key saved in the continuity data 
area. In this way, the successor program begins processing the 
file at the point where the predecessor action program left off. 


Here is an example of the printed output generated by NCSC: 
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FRANKLIN SUPPLY COMPANY 
2552 2nd. Street / Baltimore, Md. (215) 762-8800 
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5.12. CONTINUOUS OUTPUT AND CASSETTE/DISKETTE USE 


Functions available 


Use 


Most options used 
only with 
continuous output 





You can read and write, search, or position data on cassette and 
diskette auxiliary devices by using the continuous output feature. 
To do this, you move a value to the aux-function and 
aux-device-no fields of the output message area header just as 
you do when generating a continuous output message to an 
auxiliary device. Table 5-6 summarizes the settings for the 
aux-function field when reading from cassettes or diskettes. 
Print/transfer options in Table 5-2 also apply to cassette/ 
diskette. 


Table 5-6. Settings for Aux-Function Field of Output Message Header 
(Read/Search Options) 


x DS R 
Search and Read Vv 
Transparent 
Backward One D3 L E7 x 
Block 
Search and Zz U 
Position 


Table 5-6 shows that all the options specified, except 
backward-one-block and search and position, must be used with 
the IMS continuous output feature. Backward-one-block and 
search and position can be used with continuous output and 
regular output by simply moving the appropriate value to the 
aux-function and aux-device-no fields. 
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Input options There are four input options used with cassette/diskette: read, 
read transparent; search and read; and search and read 
transparent. The continuous output feature must be used with all 
these input options: 


Read option reads a block of data from. the 





cassette/diskette to the terminal screen. When you specify 
this option, don’t put any message text in the output 
message area. Also, you must move the value 4 to the 
text-length field (positions 11-14) of the output message 
area header. 





Read transparent option reads a block of data from the 


cassette/diskette, and the remote device handler deletes the 
SOE cursor sequence, carriage return codes, and DICE 
codes. 





reads a block of data from the 
cassette/diskette only if a search argument specified in the 
message text of the output message area was satisfied. 
When the argument is satisfied, the block of data is moved 
to the terminal screen. Your search argument may be in one 
of three search and read modes. Table 5-7 shows the 
formats for these modes. When you use the search and read 
option, only the contents of the output message area 
message text should be the search argument in the mode 
you choose. 


Search and read option 






Search and read transparen 
option 





“option except that the 
remote device handler removes all DICE sequences, SOE 
cursor sequences, and carriage return characters from the 
input message. 
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Table 5-7. User Message Text for Searching Cassette/Diskette 


Permissible search and 
read arguments 





Ataaaa Mode search to position the tape to a particular 
or address and then read one block, where A, 1, or 
Ttaaaa a is constant, and: 
or t 
ataaaa Is the track address (1 or 2). 

aaaa 


ls the address where the tape is to be positioned. 


Btaaaa/c...c Mode search to position the tape to a particular 
or address, search for a specific character string, 
2taaaa/c...c and read one block, where B, 2, or b is constant, 
btaaaa/c ...¢c t 


Is the track address (1 or 2). 
aaaa 
Is the block address. 


Cie 

Is the character string. Up to 16 characters can be 
specified. 

Ct/c...¢ Mode search to find the specified character 

or string, where C, 3, or c is constant, and: 

3t/c...¢€ t 

or is the track address (1 or 2). 

ct/c...c Coo 
ls the character string. Up to 16 characters can be 
specified. 





The search starts at the present tape position. 


displays the address of the 
cassette/diskette device on the terminal screen. To use this 
option, you must use the continuous output feature and must 
specify the value 4 in the text-length field (positions 13-14) of 
the output message area header. 





Report address option 


The two. other options available for cassette/diskette are the 
search-and-position and backward-one-block options. Only these 
two options can be used with both continuous and regular output 
messages: 





Search-and-position option positions the 


cassette/diskette to the block requested in the search 
argument that your action program supplies in the output 
message text. Your output message text cannot contain any 
other entries. 


repositions the 
The aux-device-no 
field must be set and the text-length field in the output 
message area must be 4. 


Backward-one-block option @ 
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Continuous output message When performing these functions, you can also insert into the 

identifier code 4-character continuous-output-code field (positions 9-12) of the 
output message area header a code that identifies the continuous 
output message you generated. This code is, as you know from 
our discussion of IMS delivery codes (5.9), returned to the 
successor program as part of a 5-character input message. If you 

If no code specified do not specify a code, the first four characters of the input 
message contain binary zeros. 


Using the continuous- The continuous-output-code field assumes special importance 

output-code field when you use any of the four input options or the report address 
option for cassettes and diskettes. When you specify one of 

Delivery notice only for these options in your action program, a delivery notice is 

unsuccesstul transmission —_ returned to the successor program only if the message was not 
successfully delivered. Otherwise, there is no input to the 
successor program until a message is transmitted from the 
cassette/diskette via the terminal screen, or until the 
auto-transmit feature is set on to allow data to be transmitted 
from the cassette/diskette. 


Screen bypass and the When using a screen bypass terminal, you must first set the 

AUTO-TRANSMIT feature control page for that terminal to take advantage of the 
auto-transmit capability. If this is not done for any of these five 

Effect of not setting options and a successful delivery notice is returned by the 

control page cassette/diskette device, the screen bypass terminal will stay in 
the interactive mode because no message is sent to IMS. 


Importance of continuous Because a successor action program may receive as input either 

output message code a delivery notice error or an input message from the cassette or 
diskette, the CONT-OUTPUT-CODE specified by the predecessor 
action program should be easily distinguished from the first four 
characters of any input message being read from the cassette or 
diskette. In this way, the successor program determines what 
type of input message it receives (i.e., delivery notice error or 
input message text) and processes it accordingly. In either case, 
the successor action program must be capable of handling both 
unsuccessful delivery notices and standard input messages. 


UP-9206 
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5.13. INITIATING A TRANSACTION AT ANOTHER TERMINAL 
(OUTPUT-FOR-INPUT QUEUEING) 


Definition 


Configuration requirement 


The third special capability of an output message generated by 
an action program is to initiate a transaction at another terminal. 
We call this output-for-input queueing. It means that an output 
message generated by that program is queued as input to a 
terminal other than the source terminal. This terminal is identified 
by the action program generating the output message. This 
output message is, in fact, a transaction code that intitiates a 
transaction at the distant terminal. Figure 5-10 illustrates how 
this happens. 


ACTION 
PROGRAM 





Figure 5-10. Generating Output Message Using Output-for-Input Queueing 


To use output-for-input queueing, specify CONTOUT=YES in the 
OPTIONS section of the IMS configuration. 


When you configure CONTOUT=YES, IMS automatically includes 
support for unsolicited output. 


5.14. HOW YOU CODE USING OUTPUT-FOR-INPUT QUEUEING 


Use CALL SEND to 
transmit output message 


Identifying the terminal 
receiving output message 


You must transmit any output message that initiates a 
transaction at a different terminal as a CALL SEND. In addition, 
your action program moves the hexadecimal value C9 or the 
character | to the aux-function field (position 15) of the output 
message area header. This value tells IMS to queue the output 
message generated as input to another terminal. You identify the 
terminal receiving the input by moving its configured value to the 
destination-terminal-id field (positions 1-4) of the output message 
area header. The configured value was_ specified during 
communications network definition. Figure 5-11 shows the 
coding required to accomplish these functions. 
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Figure 5-11. Coding an Output Message with Output-for-Input Queueing 


Transaction code initiates The only other requirement is that the output message contains 
new transaction the transaction code that initiates the new transaction at the 
destination terminal. This code, and any other output generated 
along with it, is queued immediately as input to the destination 


terminal. 
Effect of abnormal lf, after issuing the CALL SEND using output-for-input queueing, 
rermninalien the action program terminates abnormally, the new transaction is 
@ still generated at the destination terminal. 


Effect of busy destination _|f the destination terminal is in interactive mode when the SEND 

terminal status function is executed, that is, an IMS transaction is already in 
progress, or if it already has outstanding input messages queued 
for it, a new transaction can't be scheduled. In this case, the 
action program issuing the SEND _ function receives’ an 
unsuccessful status-code in the program information block. See 
5217: 


When an action program generates an output message and 
requests that it be queued as input to another terminal, IMS 
validates the output message area header and the status of the 
destination terminal identified to receive the message. Validation 
Indicating errors to errors are indicated to the originating action program by values 
originating program returned to the status-code and detailed-status-code fields in the 
program information block. Any errors found while scheduling the 
next transaction are reported directly to the destination terminal. 
Reporting output message _ Errors found in the action program processing the new 
ens transaction at the destination terminal are reported to that action 
program. As a result, this program must be prepared to handle 
such error conditions, and if necessary, to report these 
conditions to the originating terminal. 
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Error codes 


Termination restrictions 


For a complete listing of error codes that IMS returns to the 
status-code and detailed-status-code fields of your action 
program following the SEND function, see Table 5-7. 


Generally, a program that generates output using the 
output-for-input queueing option terminates with normal 
termination; however, it can specify external succession. It can't 
terminate with delayed succession. 


5.15. OUTPUT-FOR-INPUT QUEUEING WITH CONTINUOUS OUTPUT 


Create records at terminal - \t is fairly common to use the output-for-input queueing and 


print them at another 


continuous output options together. For instance, one transaction 
could create the records you want printed and write them to a 
MIRAM file. The last stage of this transaction generates an 
output message using output-for-input queueing at a destination 
terminal where the printing of the records is actually done. The 
transaction initiated at the destination terminal reads the MIRAM 
file and prints the message as continuous output. 


5.16. OUTPUT-FOR-INPUT QUEUEING WITH A SCREEN BYPASS DEVICE 


Screen bypass 


Only means of entering 
input 


Another situation where you can use the  output-for-input 
queueing is with a screen bypass device on Universal Terminal 
System (UTS) terminals. This device is defined to the 
communications network (ICAM) as a logical terminal. However, 
it has no physical medium for entering input. The only way to 
access a screen bypass device is to use the output-for-input 
queueing option. Another terminal in the IMS network generates 
(through an action program) an output message that initiates a 
transaction at the screen bypass device. This could be a 
continuous output transaction, and a report could be generated 
as Output on a printer attached to the screen bypass device. 
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® 5.17. MESSAGE SWITCHING 


SWTCH transaction IMS provides a special action program that switches messages 
from one terminal to another. You need only to enter the 
transaction code SWTCH at any terminal in your IMS network, 
identify the destination terminal for the message, and key in the 
message itself. IMS handles the rest. For more information about 
this and other terminal commands, consult the IMS terminal users 
guide, UP-9208 (current version). 


Action program initiated The message switching capability we're interested in here is one 

message switching that operates from within your own user action program. For 
instance, an action program could direct error messages to the 
master terminal when the originating terminal is unable to handle 
the error. Or, take the case of an action program that initiates a 
transaction at a distant terminal. The distant terminal could send 
the originating terminal a message indicating the transaction was 
initiated or, as the case may be, successfully completed. 


Required coding To send messages to other terminals, an action program must 
move a value to the destination-terminal-id field (positions 1-4) in 
the output message area header. Figure 5-12 shows the coding 

@ to send a message to another terminal. 


Sending messages tothe You can send a message to the system console or master 

console workstation if console support is configured. To send a message 
to the console or master workstation, enter the name ‘1CNS’ in 

Message size restriction the destination-terminal-id field. When you send a message to 
the console, your message may not exceed 120 characters. For 
more information about the system console and master 
workstation, see the IMS terminal users guide, UP-9208 (current 
version). 


EDIT CODES 
i @ BLANK AFTER 
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Figure 5-12. Coding for Message Switching 
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IMS transmits the message destined for the distant terminal or 
console by using the SEND function. The message does not go 
to the destination terminal until the program terminates. In this 
respect, message switching is handled no differently by IMS than 
any other output message. (See Figure 5-13.) 


INITIATES 
IMS ACTION 


TRANSACTION PROGRAM 
: TERMINATES 





Figure 5-13. Generating Switched Output Message 


If the transaction is terminated abnormally or canceled before the 
action program that generated the messages terminates, all 
output messages generated are deleted from the output message 
queue and no messages are delivered. IMS sends a message 
only to the originating terminal indicating the reason for 
termination. 


As we previously mentioned when discussing the SEND function, 
you should specify disk queueing when generating your 
communications network if your action programs use the SEND 
function frequently. Also, you must specify the UNSOL=YES 
parameter in the OPTIONS section of the IMS configuration to 
use the SEND function. 
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SEND FUNCTION STATUS CODES 


Selecting notification of In this section, you have seen how many of the output messages 


successful SEND function generated are transmitted using the 
Whenever the SEND function takes place, 


IMS SEND _ function. 


if you have specified 


ERET=YES in the IMS configuration, then IMS notifies the action 
program whether or not the SEND function was successful. It 


does this by placing binary values in 


the status-code and 


detailed-status-code fields of the program information block. 
When control returns to the action program, you’ should 
interrogate these fields to determine the status of the CALL 


SEND. 


PIB needed to determine To interrogate the status and detailed status code fields, you 


SEND function result must define the program information block 


on the file description 


form. Also, you must define the two fields and their location on 
the input form. Status-code occupies positions 1-2 of the 
program information block; detailed-status-code occupies 


positions 3-4. 


Action program checks After the SEND function takes place, the program should read the 
SEND status status and detailed status code fields to determine whether or 


not the SEND was_= successful. These 


fields are extremely 


important to a programmer when debugging action programs. 
Debugging is discussed in detail in Section 7. 


Result of not being notified |f you don't specify ERET=YES, and the CALL SEND isn’t 
of unsuccessful SEND successful, the action program does not regain control and IMS 


function 


abnormally terminates your action program. We_ strongly 


recommend that you always configure ERET=YES. 


Status codes Table 5-8 lists the values that IMS can return after the SEND 


function takes place. 


Trace values IMS returns trace values to the status-code and detailed- 
status-code fields when ERET=YES is configured. 
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Table 5-8. Status Codes and Detailed Status Codes Returned 
Following the Send Function 


Successful 

Parameter error 

UNSOL=YES or CONTOUT»YES wasn't 
configured, or no process files were created in 


ICAM network definition. 


Returned when output-for-input queueing is 
requested and: 


1. destination terminal is in interactive mode; 
2. destination terminal has an input message 
on queue; 


3: ZZHLD or ZZDWN command was entered 
for destination terminal; 


4. destination terminal is marked physically 
down to ICAM; or 


5. IMS can't allocate a main storage buffer 
(multithread only); INBUFSIZ — specifi- 


cation Is inadequate. 


Destination terminal physically or logically down; 
message queued 


Invalid destination terminal, auxiliary device, or 
auxiliary function specified 


No ICAM network buffer available 


Disk error, or recoverable system error on output 
message to console 


Invalid length specification 


Detailed status code=2 IMS returns a status code of 6 and a detailed status code of 2 
only when you use the SEND function to initiate a transaction at 


another 


terminal 


(output-for-input queueing). The conditions 


causing this error are not permanent. The output message header 
is valid, and you may be able to retransmit the same message 


successfully at a later time. 
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@ Detailed status code—3 Some of the conditions causing a detailed status code of 3 (with 
status code 6) are the same as those for a detailed status code 
of 2. However, this error is returned when you use the SEND 
function for message switching, not output-for-input queueuing. 
In this case, the message sent is queued for the destination 
terminal and is automatically transmitted when the terminal is 
operational. 


Detailed-status-code=4 On the other hand, when internal message control returns the 
detailed-status-code value 4 after the SEND function, this means 
that the contents of the output message area header are not 
valid. Any effort to retransmit the same message is unsuccessful. 


When this value is returned, check your action program for one 
of the following errors: 





(positions 1-4) of the 


output message area header is not a valid configured 
terminal identification. 






(position 16) of the output 





message area header is invalid. 


position 15) of the output message 
area header contains the hexadecimal value C3, F3, or F7, 
indicating that the program attempted to generate continuous 
output. You cannot transmit continuous output as a CALL 
SEND; it must always be transmitted as a CALL RETURN when 
the program terminates (5.7). If the message was addressed to 
the system console (destination-terminal-id 1CNS), only the 
hexadecimal values OO or C9 are acceptable. 


e 
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5.19. DISCONNECTING A LINE FROM AN ACTION PROGRAM 


Purpose The line disconnect feature allows an action program to 
disconnect a single-station dial-in line following the delivery of its 
output message to enable another terminal to dial in on the same 

Configuration requirements line. To use the line disconnect feature, you must include the 
continuous output capability in your configuration by specifying 

Available only for CONTOUT=YES in the OPTIONS section. The line disconnect 

dedicated networks feature is available only in a dedicated ICAM network, not a 


global network. 


To disconnect a line after message transmission, the action 


program must: 


Aux-function value, X‘C3' ™ place a continuous output flag 
(X'C3’) in the aux-function byte 
(position 15) of the output message 
header; and 


Use external succession and @ specify external succession. with 
HANGUP successor-id ‘HANGUP’ as the successor by 
setting the termination-indicator 
(position 11) in the program 
information block to E and the 
successor-id (position 5) to 


‘HANGUP’. 
HANGUP, IMS action HANGUP is an action program supplied by IMS that terminates 
program with a special code causing IMS to issue a line release/line 


request sequence to ICAM to disconnect the line. 


Delivery notice before After the output message is sent, no further input is required 
scheduling from the terminal operator. IMS waits for ICAM notification of 
successor, 
HANGUP. In this way, delivery of the message prior to the line 


message delivery before scheduling the external 


disconnect is ensured. 


Figure 5-14 shows the output specification form coding used to 


disconnect a line from an action program. 
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Figure 5-14. Coding a Line Disconnect from an Action Program 
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5.20. SENDING MESSAGES TO THE SYSTEM CONSOLE 


Configuring 
console support 


Terminal-id is 
1CNS 


When IMS session 
has a master 
workstation 


Types of output 
you can send 


Auxiliary devices 
not supported 


Message length 
restriction 


No screen formats 


Messages not edited 


No message waiting 
signal 


Your action program can send output messages to the system 
console if console support is configured. You configure console 
support by specifying OPCOM=YES in the OPTIONS section of 
the IMS configuration or by not specifying a master terminal in 
any TERMINAL section. 





place the terminal-id 1CNS_ in th 
destination-terminal-id field (positions 1-4 
of the output message header. 


Sometimes an IMS session has a master workstation associated 
with it. A master workstation is a workstation from which the 
IMS start-up job control stream is entered, or it may be defined 
in the job control stream. When there is a master workstation 
and you use the destination-terminal-id 1CNS, your output 
message goes to the master workstation instead of the console. 
When the master workstation logs off or is disabled, then the 
message goes to the console. 


You can send normal output, multiple output, switched output, 
continuous output, and output-for-input queueing messages to 
the system console. However, there are certain restrictions on 
output to the console: 


You cannot send output to an auxiliary device at the system 
console. The only auxiliary function settings you can use are 
hexadecimal OO, C3 = (continuous output), or C9 
(output-for-input queueing). 


> The maximum length of the output message is 120 
characters, not including the output message header. 
Additional characters are truncated. 


Because of the message length restriction, you cannot output 
a screen format to the console. 


> Output messages are not edited. DICE functions, FCCs, and 
other control characters appear as blanks, or in a few cases 
as printable characters. 


> There is no message waiting signal. Switched and multiple 
output messages are sent out immediately. 
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Error Returns on Output to the Console 


IMS returns a status code of 6 and detailed status code of 4 
when you attempt to send output to an auxiliary device at the 
system console. These are the same codes IMS returns when 
you have an invalid destination-terminal-id, auxiliary device, or 
auxiliary function specification on output messages to regular 
terminals. 


When your output message can’t be delivered because the 
console is physically or logically down, the action IMS takes 
depends on the type of output message. 


> With a switched message, IMS returns a status code of 6 
and detailed status code of 6. With a continuous output 
message, IMS returns a delivery notice status of X‘86’. 
These codes indicate recoverable system errors. 


b With other types of output messages (such as normal output 
in response to input from the console), IMS returns a 
successful status code of O. The reason IMS does this is 
that an error status would cause a ‘‘TRANSACTION 
CANCELLED” message to be sent to the console, and this 
could cause an abnormal termination of the IMS session. 
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6. Using Screen Format Services 
To Format Messages 


6.1. DISPLAYED FORMATTED SCREENS 


In Section 4, we briefly discussed using screen format services 
to format output messages. The sample action program JAADD1 
used screen format services to generate its output screens. 


Saves programming effort With screen format services, generating output screens is easy 
because the screens are predefined using the screen format 
generator. You don't have to include device control characters in 
your action program. In addition, screen format services does 
validity checking of input data, thereby reducing the amount of 
input validation you must do in your action program. 


6.2. DEVICES SUPPORTING SCREEN FORMAT SERVICES 


Terminals supporting You can direct screen formats to any display terminal supported 

screen formats by IMS except the IBM 3270 terminal, and also to auxiliary 
devices attached to display terminals. UNISCOPE 100 and 
UNISCOPE 200 terminals must have the screen protection 
feature, and UTS 400 terminals operating in native mode must 
have the PROTECT/FCC switch set to FCC and the control page | 

Local workstation set to XMIT VAR. For local workstations, specify a line buffer 

consideration length of at least 900 words on the LBL option of the ICAM 
network definition. 


6.3. GENERATING SCREEN FORMATS 


Screen formats generated YOu define your screen formats offline from IMS by executing the 

offline screen format generator. (See the screen format services 
concepts and facilities, UP-8802 (current version).) When you 
create each screen format, you assign a unique name to it. The 

Formats stored for later use SCreen format generator stores the formats in the system screen 
format library $Y$FMT or other MIRAM disk file. The screen 
formats for an IMS session may reside in one or two screen 
format files. 
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NOTE: 


To use screen format services, you must generate a supervisor in 
consolidated data management (CDM) or mixed mode. However, 
you can configure IMS in either CDM or DTF mode. See the IMS 
system support functions user guide, UP-8364 (current version). 


6.4. CONFIGURATION REQUIREMENTS 


Affected parameters 


Number of terminals using 
screen formats 


Number of resident 
screen formats 


Work area required 


Determining size 





When using screen format services, you must give special 
consideration to four parameters at IMS configuration: 


the | parameter; 










the. parameter; 


the parameter; and 


the. 





You must include the SFS parameter in the OPTIONS section of 
your IMS configuration. With this parameter, you specify the 
maximum number of terminals that will use screen formats at the 
same time. Be sure to specify a large enough number of 
terminals. A screen format is considered in use at a terminal 
from the time the operator requests it until the format is 
displayed, input entered, and the input acknowledged. 





With the RESFMT parameter, also in the OPTIONS section, 
specify the number of screen formats you want retained in main 
storage between calls to screen format services. The default is 1 
for single-thread IMS and 3 for multithread. 





You must configure a work area for each action program using 
screen format services. The RPG II action program itself does not 
use this area, but the compiler does. You include the WORKSIZE 
parameter in the ACTION section of the configuration. Its format 
is WORKSIZE=n. The n denotes work area size. The size you 
specify must be large enough to accommodate all variable output 
data generated by the action program plus 99 bytes for the RPG 
ll indicators. 
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Maximum OMA size Specify the OUTSIZE parameter in the ACTION section of the 
configuration (OUTSIZE=n). The n denotes the maximum size of 
the output message area for a particular action. 


‘Where the screen format \When you request a screen format in your action program, you 

is built have it built in the output message area or in dynamic main 

Using output message area Storage. If you use the output message area, it must be large 
enough to handle the screen format buffer constructed by the 
screen format coordinator. This buffer contains all variable output 
data, display constants, and device control characters. See the 
IMS system support functions user guide, UP-8364 (current 
version) for information on calculating the size of the output 
message area. 


Using dynamic main storage The advantage of building the screen format in dynamic main 
storage is that you don’t have to calculate the size needed for 
the format buffer. You must still allocate an output message area 
large enough to contain the output message header and your 
variable data fields. The OUTSIZE=STAN specification will give 
you an adequate output message area size. 


When OUTSIZE is When the action program requests a screen format and the 

insufficient output message area is not large enough to contain the format 
buffer, IMS returns an error code in the status fields of the 
program information block. IMS also places the output message 
area size required in the text-length field (positions 13-14) of the 
output message area header. 


6.5. REQUIREMENTS AT IMS START-UP 


Device assignment sets When using screen format services, you must include a device 
assignment set for each screen format file in the job control 
LFD names stream at IMS start-up. Use the LFD name TCO1FMTF for the 


primary file and TCO2FMTF for the secondary file, if there is one. 


Figure 6-1 illustrates the steps required to create and use screen 
formats with IMS. 
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CREATE SCREENS 
USING OS/3 
SCREEN FORMAT 
GENERATOR 


WRITE ACTION SCREEN 
PROGRAMS USING FORMAT 
SCREEN FORMATS FILE 1 


CONFIGURE IMS 
WITH SFS, RESFMT, 
OUTSIZE, AND 
WORKSIZE PARAMETERS 


PROCESS 
TRANSACTIONS 
USING 
SCREEN FORMATS 


START UP IMS 
WITH DEVICE 
ASSIGNMENTS FOR 
SCREEN FORMAT 
FILES 








Figure 6-1. Creating and Using Screen Formats 
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6.6. HOW IMS HANDLES SCREEN FORMATTED MESSAGES 


Retrieves screen format When your action program requests a particular screen format, 
IMS retrieves the format from the screen format file and places it 
in the output message area or in dynamic main storage. (When 
you assign two screen format files, IMS checks TCO1FMTF first, 
then TCO2FMTF.) 


Variables moved to work — The variables in the output message area are moved to the work 

area area defined at configuration. The variables remain there for as 
long as it takes the screen format coordinator to construct the 
screen in the buffer area. 


Display contents moved The screen format coordinator places the output display 
to screen buffer constants of the format into their respective locations within the 
screen buffer. These constants are always protected. 


Variables moved to When the screen is built, the screen format coordinator inserts 
screen buffer the variable data from the work area into the appropriate 
locations in the screen buffer. 


Screen displayed on When the program terminates, the screen format and variable 
®@ terminal data are transmitted to the terminal. 
Example Figure 6-2 shows an output screen containing display constants 


and variable data. Underlines represent input fields. 


PERSONAL CREDIT REPORT 


NAME: JOHN DOE 
ADDR:1552 MAIN ST. STATE:PA ZIP219140 


ACCOUNT NO: 193-A564 
BALANCE : 350.00 
PAYMENT: 





Figure 6-2. Output Screen Format with Display Constants, Variable 
Data, and Input Fields 


Using input and output Any field you define as input, or both input and output, in your 
screens action program is an unprotected field. This means that the 
terminal operator is free to change that field when making entries 
on the screen format. It is protected if you define a variable data 
Example field as output only when you build a screen buffer. In Figure 
6-3, the terminal operator has changed the address field and 
& entered a payment amount and date. 
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PERSONAL CREDIT REPORT 


NAME: JOHN DOE 
ADDR:224 PINE ST. STATE:PA ZIP:219192 


ACCOUNT NO: 193-A564 
BALANCE :350.00 
PAYMENT: 25.00 DATE: 12/23/80 





Figure 6-3. Input Screen Format with Display Constants and 
Changed Input Fields 


Output-only screens required \When your action program terminates with delayed succession or 


for: delayed succession 
continuous output 
message switching 


Function keys cancel 


screens 


When multiple screens are 
generated 


uses continuous output, IMS forces the screen format to be 
output only. Also, you must use an output-only format for any 
screen formatted output message switched to a_ different 
terminal. 


The message wait key and function keys cancel any screen 
format currently effective at the terminal. 


An action program may send multiple formatted messages to the 
originating terminal; however, only the last format may be used 
for entering data as input to the successor program. 


6.7. USING FORMATTED SCREENS FOR INPUT 


Checking input for terminal 
commands 


All commands cancel 
screens except 
ZZRSD 


Results when ZZRSD is 
entered 


When an invalid transaction 
code is entered 


When the terminal operator fills in input data, the data is 
validated before IMS passes control to the successor program. 
IMS checks the message for terminal command input before 
requesting the screen format coordinator to validate the entries. 
If the input message contains a terminal command other than 
ZZRSD, IMS processes it accordingly and cancels any screen 
format currently effective at the terminal. 


Normally, ZZRSD causes the last output message to be sent 
again, thus retaining the current screen format. However, if the 
screen format is built in dynamic main storage instead of the 
Output message area, it can’t be sent again and the screen 
format is canceled. The terminal operator receives a NO MSG IN 
QUEUE message and can’t enter input on the formatted screen. 


When the input message contains a transaction code, IMS 
verifies the code and if it is invalid, sends the message back to 
the terminal and blinks the transaction code. This does not 
cancel the screen format currently effective at the terminal. 
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Validating input data When the input message does not contain a terminal command 
or invalid transaction code, IMS requests the format coordinator 
to validate the message. If the input data filled in by the terminal 
operator is valid, IMS places only that data into the input 

No other editing message area of the successor action program. IMS does not 

performed on input perform any other editing on this input. Your action program then 
begins processing. 


When input data is invalid \When some of the input data is invalid, 
the screen format coordinator blinks the 
invalid fields. The terminal operator can 
correct the input until the retry count 
specified at screen format generation 
time is exhausted. (See screen format 
concepts and facilities, UP-8802.) 





Error codes returned for Once the retry count is exhausted, the successor program 

invalid data receives control. At that point, the program information block 
contains a status code of 7 and a detailed status code of O. (See 
Table 6-1 for a description of error codes returned when using 
screen format services.) 


Specifying type of In order for the successor program to receive this data, the 

termination predecessor action program must_ specify E  in_ the 
termination-indicator field (position 11) of the program 
information block. If that program terminated with normal 
termination (N in the termination-indicator field), the first input 
field entered on the screen format must be a valid transaction 
code that will schedule the appropriate action program to 
process the input data. 
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6.8. CODING REQUIRED TO USE SCREEN FORMAT SERVICES 


Output form coding 


Required entries 


To build screen in 
dynamic main storage 


Example 





To use a formatted screen, you make the following entries on 
the output form: 


> The character K in column 42 


> Length of the screen format name 
in column 43 


> Screen format name _ itself in 
columns 45-70 


To build the screen format in dynamic 
main storage, move ‘D’ to_ the 
SFS-location field (position 6) of the 
output message header. 





Figure 6-4 illustrates how you code the output form to build a 
screen format containing variable data in dynamic main storage. 


STACKER SELECT! 


FeFETCH OVERFLOW 
= itd COMMA! 
PBL NEGATIVE VALUE INDICATION | wcemy ei 
; [None Tce | 


€ND 
POSITION 
7 1N 
ouTPut 
RECORD 




















QUART! } 
QU ARTZ PEt icr ii la 








QUART 3. 1) tb ta aa aa ba 

QUART | Fie} TiS tise i og 
SALES 16,7 

QUOT A, 
RESULT 





























Figure 6-4. Coding the Output Form to Use Screen Format Services 
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Defining the screen format You indicate that you are using a screen format on the first field 
description for the output file. Only one screen format is allowed 
for each output record. In Figure 6-4, the output file is OMA. As 
you notice, the screen format is the first field description for the 
file. The character K in column 42 indicates you are using screen 
format services. The number 6 in column 43 is the length of the 
format name. MRKT82 is the format name as it was defined at 
screen format generation. 


List variable output data You must list the variable fields in the order that the screen 

in receiving order format expects to receive them. The first field always begins 
after position 16. You must allow 16 positions for the output 
message area header. 


Figure 6-5 shows the screen format described in Figure 6-4 as it 
appears at the terminal. 


MARKETING SUMMARY '82 
COLONIAL STEEL CORPORATION 


BRANCH: 7018 


& SALES SUMMARY 
QUARTER 1: $345,678,721 QUARTER 3: $322,628, 456 


QUARTER 2: $299,799,838 QUARTER 4: $349,798,951 
TOTAL SALES: $1,317,905,966 
YEARLY QUOTA: $1,288,988,955 
RESULTS: $28,916,971 + 





Figure 6-5. Output Screen Display for Figure 6-4. 





Handling screen formatted \IMS handles output messages that use screen format services 

output just like any other output message. They can be transmitted 
using the SEND or RETURN function. However, they do not 
appear at the terminal until the action program terminates. The 
terminal operator may then enter data, which is verified and 
stored in the successor program's input message area. 
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6.9. GENERATING AN OUTPUT SCREEN WITH NO VARIABLE DATA 


When there is no variable When an action program generates an output screen with no 

output data variable fields, such as an error message screen, you must move 
zeros to the text-length field of the output message area header 
before specifying the screen format. Figure 6-6 shows how you 
code the output form to do this. 


STACKER SELECT/ 
F»FETCH OVERFLOW 


OUTPUT INDICATORS 
DATA FORMAT 


[ee | = 

















i 
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Figure 6-6. Coding for a Formatted Screen without Variable Output Data 
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6.10. ERROR CODES RETURNED BY IMS 


Errors return status codes When IMS encounters a problem while using screen format 

to PIB services, it returns values to the  status-code and 
detailed-status-code fields of the program information block. 
Table 6-1 lists and describes these values. 


Table 6-1. Error Codes Returned by IMS when Using Screen Format Services 





















Named format can't be found 

Screen format services not configured 

nvalid terminal name or type 

Validation error; all error fields within variable data area are replaced by hexadecimal F's. 
Format area not large enough. The OUTSIZE=n specification wasn't large enough to handle 
screen format, variable data, and device control characters. IMS returns the correct output 
message area size to the text-length field (positions 13-14) of the output message area 


header. 


Variable data area not large enough. The WORKSIZE=n specification wasn't large enough 
o handle the variable data plus the 99 bytes for RPG I! indicators. 


nsufficient number of terminals was configured. 
Variable data specified for input format is invalid. 
Format width is greater than screen width. 

Fatal error (i/O error) 

_ Screen format incorrectly generated 

: System error 


nadequate main storage available in system; or format contains protected fields and 
terminal doesn't have protect feature or isn‘t in protect mode. 


_ Screen format services error 


Action program processing DDP transaction attempted to send screen format to initiating 
action program. 


See Appendix C for a complete listing of status and detailed 
status codes in hexadecimal. 
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6.11. TRANSMITTING FORMATTED SCREENS TO AN AUXILIARY DEVICE 


Setting output message 
header fields 


Aux-function field entries 


Example 





You can output a screen format to an 
auxiliary device - printer, cassette, or 
diskette - attached to a display terminal. 





To output a screen format to an auxiliary device, you move a 
value to the aux-function (position 15) and the aux-device-no 
(position 16) of the output message area header before 
specifying the screen format required. 


Table 6-2 lists the values you move to the aux-function field to 
accomplish this. Different values are specified for the aux-function 
field depending on whether the action program is using 
continuous output or not. 


Figure 6-7 shows the coding to transmit a formatted screen to a 
printer attached to a UTS 400 display terminal using print mode 
with space suppression. The action program involved is not 
generating continuous output. 


DATA FORMAT 
PBA 


ENO 
POSITION 
1” 
OuTeuT 
RECORD 


® €01T CODES 
B 8 BLANK AFTER 


40 43 
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|i 7} SPRNTOUT,’, | 



































Figure 6-7. Coding to Transmit Formatted Screen to a Printer 


NOTE: 


When you build a screen in dynamic main storage, all values, 
including auxiliary device numbers and functions, must be present 
in the output message header before the call is issued to screen 
format services. If any header values (except SFS-options) are 


changed after the call to screen format services, the new values 
are ignored. 
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Print 


Transparent 
O@ 
(unpredictable 
output at screen 
and auxiliary 
device) 


Print Mode 


Table 6-2. Print/Transfer Options for Writing of Screen Formats to Auxiliary Devices 









X 

(recommended ) 
xX 
(unpredictable 
output at screen 
and auxiliary 
device) 





Print Form fae 


(ESC H) 


Transfer 


All 


(ESC G) 


Transfer 
Variable 
(ESC F) 


Transfer 
Changed 
(ESC E) 


LEGEND: 


®@@OOOLAO 


Fes | 


Printer - same format as screen 


Printer — same information as screen; no carriage returns 


Cassette/diskette 
Cassette/diskette 
Cassette/diskette 


Cassette/diskette 


not available 





same format as screen; no field control characters 


same format as screen; only records unprotected fields 








X (field control 
characters not 
supported) 





X (field control 
characters not 
supported) 


same format as screen; records all fields and all field control characters 


~< 


| 
2 
© 


© 
© 
© 
© 


1) 
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7. Action Programming in a 
| Distributed Data 
Processing Environment 


7.1. BASIC DDP REQUIREMENTS AND TERMINOLOGY 


DDP requirements IMS handles distributed data processing (DDP) transactions 
through the IMS transaction facility. To use distributed data 
processing with IMS, you must include the IMS _ transaction 
facility in your software at each OS/3 system and must configure 
multithread IMS at each system. Also, you must define a global 
ICAM network that supports distributed data processing and 
include a LOCAP section in the IMS configuration for each IMS 

| system where you want to route transactions or which will route 

& transactions to you. Consult the IMS system support functions 
user guide, UP-8364 (current version) for configuration and 
network definition requirements. 


DDP terminology Let’s define some terms we'll be using throughout the discussion 
of DDP transaction processing: 











LOCAL TRANSACTION 


Transaction that is processed at the same IMS system 
where it is initiated 


REMOTE TRANSACTION 





Transaction that is initiated at one IMS system and 
processed at another 


IMS system where a remote transaction is initiated. In our 
illustrations we call this system IMS1. 








+ 
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SECONDARY IMS 


IMS system where a remote transaction is processed. 
The action programs processing the transaction and any 
files they access are located here. In our illustrations we 
call this system IMS2. 


LOCAL IMS 


Your IMS system, regardless of whether your system is 
primary or secondary for a particular transaction 


REMOTE IMS 
IMS system at another computer 


LOCAP-NAME 


The 4-character label of a LOCAP macroinstruction in 
your ICAM network definition, identifying a local or 
remote IMS system 
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e 7.2. HOW IMS ROUTES REMOTE TRANSACTIONS 


Transaction routing types 


Operator-initiated 
transaction 





There are three different ways in which the primary IMS can 
route a transaction to a secondary system: 





Directory routing 


The terminal operator enters a transaction code that identifies a 
transaction at a secondary system. The transaction code is defined in the 
configurator TRANSACT section. 





Operator routing 


The terminal operator prefixes the transaction code with a route character 
(followed by a period) that routes the transaction to a secondary system. 
This route character is defined in the configurator LOCAP section or in a 


PARAM job control statement at IMS start-up. 





Action program routing 


The terminal operator enters a transaction code that initiates a transaction 
at the primary system. The action program processing this local 
transaction issues an ACTIVATE function call to initiate a transaction at a 


secondary system. Action programs initiating remote transactions are 


written in COBOL or basic assembly language (BAL). 





From the programmer's viewpoint, directory and operator routing 
are the same, because they are both initiated by a _ terminal 
operator. Once the transaction is routed to the secondary 
system, an action program or series of action programs at that 
system interacts with the terminal operator the same way as in a 
local transaction. No action programs are involved at the primary 
system. 
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ACTION 
PROGRAMS 





Program-routed transaction \Vith action program routing, action programs at the secondary 
system don’t interact directly with the terminal operator. They 
return a message to the initiating action program or its 
successor, which in turn, outputs a message to the terminal 
operator. 


pone ACTION 
PROGRAMS PROGRAMS 
(COBOL OR BAL 
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& 7.3. PROCESSING A REMOTE TRANSACTION 


As an RPG Il programmer, you may be writing action programs at 
a secondary IMS to process transactions initiated by an operator 
or an action program at a primary IMS system. 


ACTION 
PROGRAMS 





Similar to processing There is little difference between the way you process a remote 
local transaction transaction and the way you process a local transaction. You can 
_ probably use the same action programs to process both local 
@ and remote transactions. 


Receiving input message VWhen the transaction begins, you receive an input message 
starting with a 1- to 8-character transaction code, just as with a 
local transaction. 


Determining input You can determine the source of the input message by testing 
message source the DDP-mode field of the program information block and the 
source-terminal-id field of the input message header. 


DDP-mode field The DDP-mode field (position 70 of the program information 
block) contains the value ‘R’ when the transaction is 
operator-initiated (either directory routing or operator routing). It 
contains the value ‘A’ when the transaction is initiated by an 
action program. When a transaction is local, the DDP-mode field 
contains zeros. This field has other possible values but they 
apply to action programs at the primary IMS system. 





Source-terminal-id field When an action is scheduled to process a transaction at a 
secondary IMS, the source-terminal-id field (positions 1-4 of the 
input message header) contains the locap-name of the IMS 
system originating the transaction rather than a terminal-id. You 
can't test for the actual terminal initiating a remote transaction. 
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General restrictions 


SEND function restriction 


Continuous output 
restriction 


Auxiliary device 
restriction 


There are a few general restrictions on processing remote 
transactions. (There are . several additional restrictions for 
program-initiated remote transactions, which we'll discuss a little 
later.) 





You can’t use the to output a message to the 
originating terminal (or any terminal at the remote IMS). 
However, you can use the SEND function to output a 
message to a terminal at your local IMS. (See 5.17.) 
Afterwards, clear the destination-terminal-id field (positions 
1-4 of the ouput message header) or move the source 
locap-name to that field before sending an output message 
to the originating terminal. 





You can’t sen o the originating terminal. 
Again, you can use the SEND function to initiate continuous 
output at a local terminal using output-for-input queueing. 





You can't send output to an attached to the 
originating terminal. However, you can send output to an 
auxiliary device at a local terminal using the SEND function. 
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7.4. PROCESSING AN OPERATOR-INITIATED REMOTE TRANSACTION 


With the few exceptions we've already mentioned, you process 


an operator-initiated remote transaction the same way as a local 
transaction. 


Action program You can use any type of action program succession with 

succession operator-initiated transactions. Once the transaction begins, the 
IMS transaction facility establishes a communications link which 
stays in effect until the transaction ends. When you use external 
succession, the terminal operator receives and responds to your 
output messages without entering any additional codes. 


Figure 7-1 illustrates a remote dialog transaction, using both 
internal (either immediate or delayed) and external succession. 


ACTION 
PROGRAM 





| ACTION | 
PROGRAM 


2 


ACTION 
1 PROGRAM 
3 





Figure 7-1. Processing an Operator-Initiated Remote Dialog Transaction 


Screen format services You can use screen format services with operator-initiated 
in DDP remote transactions. (See 7.6.) 
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7.5. PROCESSING A PROGRAM-INITIATED REMOTE TRANSACTION 


Considerations and 
restrictions 


Output message 
formatting 


Screen formatting 
restriction 


Allowable termination 
types 


When a remote transaction is initiated by an action program, you 
send an output message back to the originating action program's 
successor. That action program in turn outputs a message to the 
terminal operator. 


Because your output message goes to an action program rather 
than to a terminal, there are a few additional considerations and 
restrictions: 






-you don't need control characters. Of course, 


di 


you may want to use the same output message for either 
operator- or program-initiated transactions. In this case, the 
action program receiving your message must be prepared to 
receive your control characters. 






you return to the originating action program or its successor. 
However, you can use the SEND function to display a screen 
format at a local terminal. 





you return an 
output message to the originating action program's 
successor. You can’t use external succession. You can, 
however, use immediate or delayed internal succession and 
have your successor program return the output message 
(Figure 7-2). 





ACTION |. | ACTION 
PROGRAM PROGRAM 
1 


ACTION 
PROGRAM PROGRAM 
B < 2 





Figure 7-2. Processing a Program-Initiated Remote Transaction 
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7.6. USING SCREEN FORMAT SERVICES TO PROCESS REMOTE 
TRANSACTIONS 


Displaying screen format 
at initiating terminal 


Displaying screen format 
at local terminal 





When your action program processes an_ operator-initiated 
remote transaction, you can use screen format services to 
display a screen format at the initiating terminal (or at an auxiliary 
device attached to that terminal). 


SCREEN 
FORMAT 
FILE 





Whether the remote transaction is operator-initiated or 
program-initiated, you can use the SEND function to display a 


screen format at a terminal (or auxiliary device) attached to your 
local IMS system. 


TRANSACTION CODE 
ET ACTION mS] SCREEN 
PROGRAM FORMAT 


FILE 
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identifying local terminal 


Limitations of SEND 
function 


Termination types allowed 


Receiving formatted input 





To display a screen at a terminal attached to your local IMS 
system, move the terminal-id to the destination-terminal-id field 
(positions 1-4 of the output message header). Remember, you 
can display only an output format when you use the SEND 
function. Afterwards, clear the destination-terminal-id field or 
move the locap-name of the primary IMS to that field before 
sending an output message to the source terminal. 


When you display an input/output screen format at the source 
terminal (at the remote system), you can terminate your program 
normally or with external succession. We recommend external 
succession. 


When the terminal operator at the remote system enters input on 
the screen format, the successor program you name at your local 
IMS system (which could be the same action program) takes 
control and receives the input. 


ACTION 
PROGRAM 
1 


ACTION 
PROGRAM 
2 
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8. Compiling, Linking, and 
Storing Action Programs 


8.1. PREPARING ACTION PROGRAMS FOR ONLINE PROCESSING 





After you write an action program, 





What you must do Compile the action program (8.1). 


Link edit the program to create a load module (8.2). 





Store the program in the appropriate load library (8.3). 





Identify the program to IMS in a PROGRAM section of the configuration. 
(See the IMS system support functions user guide, UP-8364 (current 
version).) 





Identify the load library in the job control stream at IMS start up, unless 
programs are stored in the system load library, $Y$LOD. (See UP-8364.) 


sepa 





Scope of section This section tells you how to compile and link your action 
programs and where to store them for use during the online IMS 
session. For additional information on the job control statements 
and procedures shown in the examples, refer to the current 
versions of the job control user guide, UP-8065, and the RPG II 
user guide, UP-8067. 
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8.2. COMPILING ACTION PROGRAMS 


Action programs compiled You compile action programs the same way as other RPG Il 
like any other program programs, using the RPG job control procedure (jproc) or the 
EXEC RPGIl job control statement. Don’t use the RPGL jproc to > 
compile and link an action program. 


Using RPG jproc with Figures 8-1 and 8-2 show two ways of compiling an action 
embedded input program using the RPG jproc. In Figure 8-1, the source program 
is embedded in the job control stream. 


// JOB PROG1 
// RPG 
/$ 


source program 





Figure 8-1. Compiling an Action Program Using Jproc and Embedded 
Source Program 


Using RPG jproc with filed \n Figure 8-2, the source program, MYPROG, is filed in the 

source program system source library, $Y$SRC. When the source program is 
filed in a library, you identify the module name in the label field of 
the RPG jproc. The IN parameter gives the location of the source 
module - in this case, the system source library. 


// JOB PROG2 
//MYPROG RPG IN=(RES) 


/& 
// FIN 





Figure 8-2. Compiling an Action Program Using Jproc and Filed Source Program 

















UP-9206 


Usng standard job control 
with embedded input 


Using standard job control 
with filed source program 


SPERRY UNIVAC OS/3 8-3 
IMS ACTION PROGRAMMING IN RPG II 


COMPILING ACTION PROGRAMS 


Figure 8-3 uses the EXEC RPGII job control statement and takes , 
source input from the job control stream. You must allocate a — 
printer and two work files for the compiler. 


JOB PROG3 

DVC 20 // LFD PRNTR 
WORK 1 

WORK2 

EXEC RPGII 


source program 





Figure 8-3. Compiling an Action Program Using Standard Job Control and 
Embedded Source Program 


Figure 8-4 also uses the EXEC RPGIl job control statement. In 
this case, the source program is filed in a user source library, 
SRCIN. You identify the source module and library in a PARAM 
statement and must also include a device assignment set for the 
source library. 


JOB PROG4 

DVC 2@ // LFD PRNTR 

DVC 50 // VOL DISK®1 // LBL SRCLIB // LFD SRCIN 
WORK 1 

WORK2 

EXEC RPGII 

PARAM IN=MYPROG/SRCIN 


FIN 





Figure 8-4. Compiling an Action Program Using Standard Job Control and 
Filed Source Program 
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8.3. LINK EDITING ACTION PROGRAMS 


LINK jproc format 


Format for naming load 
module 


LINK jproc example 


Using standard job control 





After you obtain a clean action program compilation, you must 
link edit the program and store it in the appropriate load library. 
We discuss load libraries in 8.4. 


You can use the LINK job control procedure or the EXEC 
LINKEDT job control statement. On the LINK jproc, you must 
specify the OUT parameter to store the action program in a load 
library: 





// LINK action-program-name, OUT={(vol-ser-no, label) 
(RES, SY$SLOD) 


For example: 


// LINK MYPROG,OUT=(RES,$YSLOD) 


If you want to give your action program load module a different 
name than the object module, use this format: 


//load-module-name LINK object-module-name, as aero a 
(RES, $YSLOD) 





Figure 8-5 uses the jproc to link edit an object module called 
MYPROG and create a load module called CREDIT. Output is to 
LOADLIB. You don’t need a device assignment for LOADLIB 
because the LINK jproc generates it from your OUT specification. 


// JOB LINK 
//CREDIT LINK MYPROG,OUT=(IMSVOL,LOADLIB) 


/& 
// FIN 





Figure 8-5. Link Editing an Action Program Using Jproc 


When you execute the linkage editor using standard job control, 
you need a LOADM statement to name the load module and 
INCLUDE statements for the action program object module and 
the IMS link module, ZF#LINK. 
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Example using Figure 8-6 shows a standard job control stream for the linkage 

EXEC LNKEDT editor. The linkage editor requires a printer file and one work file. 
You can omit the printer file if you assigned one to the compiler 
in the same job control stream. Output is to the system load 
library, $Y$LOD; a device assignment is not needed for this file. 


JOB LNKEDT 

DVC 20 // LFD PRNTR 
WORK 1 

EXEC LNKEDT 

PARAM OUT=$Y$LOD 


LOADM CREDIT 
INCLUDE MYPROG 
INCLUDE ZFHLINK,SYSOBJ 





Figure 8-6. Link Editing an Action Program Using Standard Job Control 


Compile and link example | Figure 8-7 shows a job control stream for compiling and linking 

using jprocs an action program, using both the RPG and LINK jprocs. The 
action program is stored in the LOAD action program library (see 
8.4). The LINK jproc generates a device assignment for the load 
library. 


// JOB RPGL1 
//MYPROG RPG IN=C(RES) 
//CREDIT LINK MYPROG,OUT=(IMSVOL,LOAD) 


/& 
// FIN 





Figure 8-7. Compiling and Linking an Action Program Using Jprocs 


Compile and link example Figure 8-8 shows a job control stream for compiling and linking 
using standard job control an action program, using standard job control. A device 
assignment set is required for the output file, LOADLIB. 
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JOB RPGL2 

DVC 20 // LFD PRNTR 

DVC 50 // VOL IMSVOL // LBL LOADLIB // LFD LOADLIB 
WORK 1 

WORK2 

EXEC RPGII 


source program 


WORK 1 
EXEC LNKEDT 
PARAM OUT=LOADLIB 


LOADM CREDIT 
INCLUDE MYPROG 
INCLUDE ZFHLINK,SYSOBJ 





Figure 8-8. Compiling and Linking an Action Program Using Standard 
Job Control 
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8.4. STORING ACTION PROGRAMS IN A LOAD LIBRARY 


One library for action 
programs 


When you use fast load 
feature 


Improves performance 


Fast loading requires 
LOAD library 


Action programs loaded 
from fast load file 


When you do not use 
fast load feature 





When you link edit an action program, you must specify the load 
library where you want it stored. IMS has specific requirements 
for storing action programs. 


The first requirement is that all your action programs must reside 
in the same load library. 


The load library you choose depends on whether or not you 
configure the fast load feature by specifying FASTLOAD=YES in 
the OPTIONS section of your IMS configuration. (See the IMS 
system support functions user guide, UP-8364 (current version).) 
The fast load feature improves online performance in applications 
with large action programs or frequent action program loading. 


If you configure fast loading, place all action programs in a 
separate action program load library in unblocked format. You 
assign this library at IMS start-up with the LFD-name LOAD. At 
start-up, you also assign the fast load file, LDPFILE. The first 
time a transaction calls on a particular action program, IMS 
copies the program from LOAD to the LDPFILE. After that, action 
programs are loaded from LDPFILE. 


If you don’t want fast loading, store your action programs in 
either of two libraries (but all in the same library): 


the system load library, $Y$LOD; or 
the library containing your online IMS load module. This 


library is identified at configuration time by the LIBL 
parameter of the IMSCONF jproc. 
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8.5. REPLACING ACTION PROGRAMS IN THE LOAD LIBRARY DURING ONLINE 
PROCESSING 


You can replace action programs in the load library while IMS is 
online, whether or not you use the fast load feature. 


How to replace programs YOu replace an action program in the $Y$LOD, LOAD, or other 
load library by recompiling and relinking or by applying a patch 
(COR). For an explanation of the COR function, see the system 
service programs user guide, UP-8062 (current version). 


Fast load requirement When you use the fast load feature, you must insert the 
statement: 


// DD ACCESS=EXCR 


in the device assignment set for the LOAD library in the compile 
and link or COR job control stream. 


Recompile and link example The job control stream in Figure 8-9 recompiles and links an 
action program for output to the LOAD file. This example 
assumes you use the fast load feature. 





// JOB RECOMP 

// DVC 50 // VOL IMSVOL // DD ACCESS=EXCR // LBL LOAD // LFD LOAD 
//MYPROG RPG IN=(RES) 

//CREDIT LINK MYPROG,OUT=(IMSVOL,LOAD) 


/& 
// FIN 





Figure 8-9. Recompiling and Linking an Action Program During Online Processing 


ZZPCH command After replacing the action program in the load library, issue the 
ZZPCH master terminal command. The next time a transaction 
calls on the action program, IMS loads the new version from the 
load library. When you use the fast load feature, IMS copies the 
new version to the LDPFILE. The ZZPCH master terminal 
command is described in the IMS terminal users guide, UP-9208 
(current version). 


Adding action program Follow the same procedure to add an action program to the load 
to library library that is missing at start-up. Of course, the program must 
be defined in a PROGRAM section of the IMS configuration. 
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ALTER statement restricted \When you use the fast load feature, do not use ALTER 

when using fast loading statements in the job control stream at IMS start-up. When you 
do not use fast loading, you can insert ALTER statements in the 
start-up job control stream to make temporary changes to action 
programs. 























UP-9206 SPERRY UNIVAC OS/3 9-1 
IMS ACTION PROGRAMMING IN RPG Il 


DUMP CONDITIONS 


9. Debugging an Action Program 


As often as we might wish that nothing would ever go wrong 
with our programs, in reality that never seems to be the case. 
Since action programs can’t use the generate-debug capability 
available to other RPG II programs, it is important to be able to 
debug your action program using the snap dump feature provided 
by IMS. 


9.1. CONDITIONS FOR A SNAP DUMP 


e@ What causes a snap IMS provides a snap dump under three conditions: 
dump 


D An action program voluntarily terminates abnormally by 
moving S to the termination-indicator field (position 11) in 
the program information block. 


> An action program terminates abnormally due to a program 
check. 


b An action program terminates abnormally due to a 
timer-check (time-out due to a loop in the action program). 


9.2. TYPES OF SNAP DUMPS 


Edited and unedited snap IMS provides both edited and unedited snap dumps. In 
dumps single-thread IMS, an edited snap dump is a standard feature. 
Multithread IMS users must specify SNAPED=YES in_ the 
OPTIONS section of the IMS configuration to obtain an edited 
snap dump. The configurator then includes the module 
ZG#SNAPM that provides the edited directory for the snap dump. 
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9.3. LAYOUT OF A SNAP DUMP 


Snap dump layout Figure 9-1 illustrates the general layout of an IMS snap dump. 
This same general layout applies to both single-thread and 
multithread IMS. 


PROGRAM REGISTERS 





Figure 9~1. Layout of a Snap Dump 


Snap dump general areas AS you Can see, a snap dump is broken down into six general 
areas: edited headers, IMS and action program registers, 
interface areas, action program load area, thread control block 
(THCB), and terminal control table (TCT). 
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Header data Edited header areas contain: (1) data about which action program 
was running at the time of the snap; (2) an allocation map that 
provides the relative addresses of areas of interest within the 
snap dump; and, (3) a general statement of why the snap dump 
occurred - e.g., ACTION PROGRAM REQUESTED ABNORMAL 
TERMINATION. 


Register section The next section contains registers. There’s one or two sets of 
registers depending on the reason for the snap dump. 


Registers saved by a If you voluntarily terminated your action program by moving S to 

voluntary snap the termination-indicator field of the program information block, 
the snap dump contains one set of registers. These are IMS 
registers. They are of little use to an IMS action programmer. To 
find the registers belonging to your action program, you must go 
to relative location PIB + 4C,.¢, which contains a full word 
forward pointer. This word is the address of the SAVE area that 
contains your action program's registers. Go to this address and 
advance three full words. The next full word is register 14, then 
15, then registers O-12. Figure 9-3 illustrates these fields. 


Registers saved by an If, on the other hand, IMS terminated your action program due to 
& involuntary snap a program check or time-out, the snap dump contains two sets 
of registers, IMS and user action program registers. The user 


registers are labeled so they are easily identifiable. In addition, a 
duplicate set of user registers can be found at location PIB + 
44,,. At this location in the program information block, you'll find 
the 16-byte program status word indicating the address of the 
instruction immediately following the one that caused the 
abnormal termination. Also, right after the progam status word 
are the action program’s 16 registers (O-F). 


Interface areas Following the register section, you find the interface areas - 
program information block, output message area, input message 
area, work area, continuity data area, and defined record area. 


Program area The next section of the snap dump is the action program load 
area. It contains the executable load module that was output by 
the OS/3 linker. 


Thread control block Following the action program area is a section used for the 
action program’s thread control block. In the thread control 
block, most pointers and flags required to control the user 
environment are stored for use by IMS and indirectly by the user 
action program. 
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SNAP DUMP LAYOUT 


Single and multithread 
main storage layout 
differences 


Terminal control table 
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Figure 9-2 illustrates the relationship between the IMS thread 
control block and the user interface areas for both single-thread 
and multithread IMS. 


IMS SINGLE-THREAD 


_ 


PROGRAM INFORMATION BLOCK 
(PIB) 


OUTPUT MESSAGE AREA 
(OMA) 
INPUT MESSAGE AREA 
(IMA) 


WORK AREA (WA) 


CONTINUITY DATA AREA 
(CDA) 





DEFINED RECORD AREA 
(DRA) 


IMS MULTITHREAD 


PROGRAM !NFORMATION BLOCK 
(PIB) 


OUTPUT MESSAGE AREA 
(OMA) 


CONTINUITY DATA AREA 
(CDA) 


WORK AREA (WA) 


INPUT MESSAGE AREA 
(IMA) 


DEFINED RECORD AREA 
(DRA) 


fees 





Figure 9-2. Relation between THCB and Interface Areas 


You will notice that there are pointers within the thread control 
block that point to each interface area. The differences between 
single-thread and multithread IMS in this area are only in the 
location of these pointers and in the relative order of the 
interface areas themselves. 


The last section in the snap dump is the terminal control table. 
The data in this area is relevant to the terminal that initiated the 
action and is the least useful section of the dump to the IMS 
programmer. 
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ANALYZING A SNAP DUMP (FIGURE 9-3) 


9.4. ANALYZING A SNAP DUMP 


“Now we'll discuss in detail Figure 9-3, which is a sample RPG II 
snap dump. 


The action name is RCCUST and the current program processing 
that action is also RCCUST. The term-id (terminal identification) 
for this transaction is WS1. This is the way the workstation that 
initiated the transaction was defined in the communications 

Allocation map addresses network definition. The allocation map that follows contains the 
beginning and end locations as well as the lengths of user 
interface areas, and other areas included in the snap dump. The 
locations refer to relative addresses. Relative addresses are 
printed on the far left side of the snap dump. 


No work area or continuity The directory in Figure 9-3 shows that there are no addresses 

data area for the work area (WA) or continuity data area (CDA). The 
reason for this is that these areas were not given values in the 
configuration. 


THCB addresses If you aren't using an edited snap dump, that is, if it contains no 
directory listing, it’s still quite easy to locate all the action 
program's interface areas. Go directly to the thread control 

& Location of interface block, which is at location DO,,.. The first five full words (40 
pleas bytes) contain the relative addresses of the program information 


block, input message area, work area, output message area, 
continuity data area, and action program load area, in that order. 


Reason for snamp dump Following the allocation map on Figure 9-3 is the reason for the 
snap dump: ACTION PROGRAM REQUESTED ABNORMAL 
TERMINATION. Voluntary termination results when an action 
program moves S to the termination-indicator field (position 11) 
of the program information block. 


One set of registers The register section contains only one set of registers because 
the action program terminated voluntarily. These are IMS 
registers. To find RCCUST's registers, go to relative location PIB 
+ 4Cig. At that location, you find a full-word address of 
RCCUST’S save area. The save area contains the action program 
registers. 


SAVE area The save address is B484,,. Once at this address, which is in 
the action program load area, advance three full words. At 
location B490,, you will find register 14, and in the subsequent 
full words, registers 15 and O-12, respectively. 
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Oe ee ee ee eee ee eee 


'us@7o 


puMeP 


SNAP 


Oe ee ee ee et es ee ee ee ee ee ee eee eee ed 


ACTION NAME? xccustao OATE: 61/04/07 


CURRENT ACTION PROGRAM? PCCUSTOO TERM=ID; 4S) TRANS=1D: YOSIN061OZ4VONUI TIMES bussusis 


@e ALLOCATION MAP oe 


FROM TO LENGTH ARE AoNAHE 
ooooagon 
00004298 
eo000u000 
o000a090 
00000000 
COOGAZRR 


o0o0aner 
00004283 
odvuon000 
00004297 
o6u0000G 


vuoo0gey 
unnooolic 
vonoouno 
oonog2nse 
ovotoave 


PROGHAM INFORMATION GLOCK 
INPUT MESSAGE AREA CIMA) 
WORK AREA (WA) 

OUTPUT MESSAGE AREA (OMA) 
CONTINUITY DATA AREA (CDAD 


(Ple) 


sogoanoo 
o0g00oFa 
nooousAO 


CAUSE OF Shap 


BY ImS/90 
O-7 90001300 
8-F 69003096 


G86a000 TO 


aouoc 287 
acun0243 
ooOconoFF 
AOVONAY 


OuUMP: 


aT GCO416a 
Coon4ara 
A0004202 


Oé6AZB8 


aono2zoco 
uoonoi74 
uunooo1d0 
orgnaace 


ACTION PROGRAW 


OUOTF CIC 


OutNn0980 


ACTIUN FROGKAM LOAD AREA 
THREAD CONTROL BLOCK (THCBI 
FILE ALLOCATION MAP 


TERP’INAL CONTROL TARLE (TCT? 


RESUESTED AsttORMAL TERMINATION 


oacuugnn Oroguy43c 00004588 vovd05a4 


oonnantk Oenuav48O OuUOY7EU ANUUdU2Y 


PIB 


STATUS CODE 
DET-ST-CODE 


SUCCESSOR-ID 
TERMINATION-INDICATOR 


LOCK-ROLLBACK-INDICATOR 


vuontsou 


0U003090 


EZHHONIL UCCOVAND ACHUOOCO GVOUNGUY FeeeeRPGULUSNeveolol seseeesccesees6AlUn 





cOanéo-Onoonecs CobORYaY YOOGOONN Mnoduarc 


SAVE address 


Agua? at 


1 
DATE 


TIME SOURCE-TERMINAL-ID 


AC8G=00000960 CO000000 uooCADDD do000000 
}OADAD=4040404O 80404040 40404040 4O40404O 4O4040 


Q6a0CO TO 064280 SAME AS ABOVE 


SOURCE-TERMINAL-ID 
MA260=40404040 40404040 40404040 40404040 


:9a240-02530009 [001 qoooo 


SNAP 


so404%04%O 40404040 Q0510061 « 


WSL cee/*D6A260 


O FOO6O07FF OS Pocvceoeoit TTIPO010N Veose =COAZA0 


O6az2Be YO} 04C2B88 


TEXT-LENGTH 





Figure 9-3. Sample RPG II Snap Dump (Part 1 of 2) 
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: ACTION PROGRAM 


2BB-O5FO5@FO FOOSO7FF DONOBYO4 DPODOCDD DO0GODDN DOOOFOFY DODDD000 DODUOOUD eG eODeceeesMececoeceeeD0seessee ce 0Gh288 
'0a2D8-00000000 Q000GO0O 00000000 00000000 00000000 00000000 OODDDOND DUVONODUN eeeeceecesarnecccesecresecessces ce 0bA208 


@eee O464A2FB TO 06A318 SAME AS ABOVE 


*ERROR 


90A458-00000000 OOD0A3I2 GOOD0DOD BHAODDON | £ 3000308} 000083A0 ODDOBID0 DODUNZFH SoeereccevercceveToccveresccscese=06A4S8 


filename-CUSTFIL 
JOAFOB-0000B876 DOOOCZ8D DONDBABO ON0DBS7E |CIEHEZES C4CIOIWO COODBOOZ ZUCEODOD FecereeBoeevreeeeeCUSTFIL soveeF ees 06AF D8 
1OAFF8-00010005 [Firirira ripe FOO OHDOOOHD 00000000 O0ONDNGD OODD0000 DOODOODD Peeeelliliseescescvcceversoesecce OOAFFS 


RECORD KEY 8002 


SAVE ADDRESS —. —» REGISTER E 


’ = 


30B478- 70829260 30859202 31800609 [30853085| 


1 2 3 4 5 6 7 


108 488 00000000 |0000 0] 00N0A0441 000086927 00008896 |OO0CK4DY 60008764 FOECDGOC Fee 


8 A B c 


PARAMETER LIST 


OC118=74e2tAFF SBEO7T4HI4 G7FEC2ZC7 Sn00BIBE o00caFES ODODBCOZ BOODAFFCIODDONGOD CececccececBGreceeeeVoceesescceesDbClla 


THCB 


PIB 


OND040000A000| 00004298 | 00000000 | 00004090! DDDDDDGO 0000AZBS|ODOODOFFA ODOONUND Peecccescccsesesecccesescsessesse@060000 
D0u00000 OGHN50CO OENMOGOHS 00000000 | OODIF7OC OOOIFC9C GOODOODOD DOODVOIED SeacceecesccccsvcceTesecseressee es @OSC0F0 


DIRECTORY FOR a SNAP pr 


00110-00000: THCB+20268| 04000000 ono0coD0 =oo00AUGO 90000188 THCB+74 09000000 %..Qs- eedes 
ar 


'80130-00000000 00000000) 00000000 DaDD0N00 xcoDa0uuN 03000034_O00004€8 GooQC126 CoccreccvccccscccecccvvcsessVoshe 060130 


FILE ALLOCATION MAP 





Figure 9-3. Sample RPG II Snap Dump (Part 2 of 2) 
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ANALYZING A SNAP DUMP (FIGURE 9-3) 


9.5. THE PROGRAM INFORMATION BLOCK (PIB) 


Locating the status codes 


Locating the successor-id 
field 


Locating *ERROR 


Interpreting error codes 


Finding Your Error 





The program information block begins at address OAOO. The first 
word (4 bytes) contains the status-code and det-status-code 
fields. IMS returns values to these fields indicating the result of 
action program function calls. If the function call is successful, 
these fields contain zeros. In Figure 9-3, however, you see that 
the function call made to IMS was not successful. The value 034. 
in status-code indicates the action program made an invalid 
request. The OB, in det-status-code indicates that the file 
requested in the function call was not assigned to this action at 
IMS configuration. To find out exactly which file is involved, you 
must consult the parameter list address in the thread control 
block. We will discuss how this is done very shortly. 


For a complete listing of the values IMS returns in the 
status-code and det-status-code fields, see 2.6. 





Looking further into the snap dump at relative location PIB + 446, 
you find the successor-id field. Notice that this field contains 
‘RPGO20'. Whenever RPG II encounters an error, it places the 
appropriate error code in the successor-id field prior to requesting 
the snap. RPGO20 indicates an indexed file error. For a complete 
listing and description of error codes, consult OS/3 system 
messages, UP-8076 (current version). 





A further statement of the error condition can be found in the 
field, “ERROR. RCCUST's link relative location or link-org is O and 
*ERROR is displaced 1B0,, into it. To locate *ERROR, we take the 
start location for the action program load area that the allocation 
map tells us is A2B8,, and add 1BO;g to it. This gives us 
location A468,, or “ERROR. At this location in the snap, we find 
E3,, in the first byte and 03. and OBj., respectively, in the third 
and fourth bytes. You will recognize 03,, and OB,, as the 
status-code and det-status-code fields. The E3,, (character T) 
can be found in OS/3 system messages, UP-8076 (current 
version) and is defined as an RPGO20O error. 


At this point, it’s obvious that the wrong file name was used for 
1/O or the file requested is not available to this action program. 
In our example, the file CUSTFIL to which the function call was 
made wasn't configured for use by action RCCUST. 
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Finding Other Data in the Program Information Block 





Locating the Still in the program information block, at relative location PIB + 

termination-indicator field A,. ig the field termination-indicator. It contains an E2y¢ 
(character S) for snap dump. The value in this and any other 
program information block field varies depending on the action 
program and whether the program terminated voluntarily or 
involuntarily. 





Locating the Relative location PIB +By,, is the lock-rollback-indicator field. It 

lock-rollback-indicator field contains D5,, (character N), which is the default value. The value 
N establishes a new rollback point in the audit file (before-images 
of records to be updated) and releases all locks for this 
transaction. 


Locating other PIB fields |§ By comparing the program information block fields listed in Table 
2-6 to the program information block area of the snap dump, 
you can see exactly what values all these fields contained when 
the dump occurred. For your convenience, we have noted a few 
of these fields in Figure 9-3: transaction-date (810407), 
time-of-day (105014), and source-terminal-type (E6,, or W for 
workstation). 


Entire PIB displayed All 145-character positions of the program information block are 


displayed. Remember, however, that only the first 70 positions 
are accessible to your action program. 


9.6. THE OUTPUT MESSAGE AREA 





Locating the Using the allocation map, we see the output message area 

destination-terminal-id field begins at address AO90,,¢. This area contains the 16-byte header 
and the output message generated by the action program. Since 
RCCUST terminated abnormally before generating an output 
message, the output message area contains spaces. However, 
the header data is displayed. The first word contains the 
destination-terminal-id field. This indicates the destination of the 
output message had the program not terminated abnormally. 
Note that this value is the same as_ the value in 
source-terminal-id, which occupies the first word of the input 
message area. 
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Locating the 
message-length field 





Also, in the output message area at location AO9C,, or OMA + 
C.g is the 2-byte message-length field. This field indicates the 
size of the output message to be generated. 


Since RCCUST doesn’t use screen format services and it isn't a 
continuous output program, relative locations AQ94,, and 
A098.¢, respectively, contain zeros. 


9.7. THE INPUT MESSAGE AREA 


Locating the input message The input message area begins at relative address A298,g. Its 


contents include the input message area header (16 bytes) and 
the input data entered by the terminal operator. The terminal 
input starts at IMA + 11 or A2A8,g. The terminal operator 
entered the customer number 11111 (F1F1F1F1F1), a plus (+) 
sign (4E), and AMOUNT $1.00 (FOFOF1FOFO). These entries 
correspond to the data requested by the screen format shown in 
Figure 3-11. 


9.8. ACTION PROGRAM LOAD AREA 


Largest section of dump 


Using the thread control 
block 


Since there is no continuity data area, work area, or defined 
record area for this particular action program, we will now 
discuss the program load area. This is by far the lengthiest 
section of the snap dump. Since data contained in the thread 
control block is essential to interpreting the program area, we 
will discuss the two areas at the same time. 





In this example, the thread control block is at location DO,g. It 
contains the addresses of all the interface areas and the action 
program load area. This data is of value only if you’re using an 
unedited dump. However, the thread control block does contain 
other information very useful to the IMS programmer. 
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Locating the file allocation At THCB + 20,6 or in our example location FO,., there are four 

map full words used for a file allocation bit map. To use this bit map, 
you must realize that four full words contain 128 bits. IMS uses 
these bits to indicate which specific files a user action program 
can access - one file per bit. The file allocation map for 
multithread IMS is 8 full words long (256 bits). 


When bits are set off In Figure 9-3, no bits are on at location FO. Consequently, 
RCCUST could not access any files. If you recall, the 
det-status-code field already informed us that the file wasn't 
defined at IMS configuration. However, in cases where this same 
problem doesn't exist, the file allocation map can be very 
valuable in determining exactly which files are being accessed by 
an action program. 


When bits are set on For example, if the high order bit was on, the action program 
could access one file - the first file configured. If additional bits 
were on, additional files could be accessed. These bits are 
maintained in the same relative order as the actual files were 


configured. 

THCB + 74 Moving to relative location 144 or THCB + 74,.¢, we find three 
words that in most instances are very useful for debugging 
purposes: 


0300003A  OO00004E8 0000C128 





Determining the last The first of these words needs to be broken down into individual 

function call bytes. Byte O (03) indicates the number of parameters passed on 
the last CALL function made by the action program. Bytes 1 and 
2 are not used. Byte 3 (3A) indicates what CALL function was 
issued. In this case, it was a GETUP function with three 
parameters passed. 


Although the RPG Il action program appears to access files 
normally without issuing function calls, RPG Il is in fact, issuing 
these calls to IMS. 


Table 9-1 lists all the IMS function calls and their corresponding 
hexadecimal values for use in debugging your action program. 
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Hexadecimal equivalent for 
function calls 


Locating the DTF 


Locating the parameter list 


Table 9-1. Hexadecimal Equivalents for Function Calls 





















RETURN 


OA SEND 
26 ESETL 
2A SETL 
2E INSERT 
32 DELETE 
36 PUT 
3A GETUP 
3E GET 
4A SNAP 


SUBPROGRAM 





The second word of this 3-word group is the relative address of 
the DTF referenced by the function call if it was an I/O function. 
This address is not within the range of the user snap dump and 
is useful only when a job dump is available. 





The last word of the group is the address of the parameter list 
that was passed for the function. In our example, the relative 
address of the parameter list is C128... This address is in the 
action program load area. Since three parameters were passed in 
the call, the next three full words are the addresses of those 
parameters. The first address is the file name. It’s at location 
AFE8,, in the program area. At this location, we find a 7-byte 
constant, CUSTFIL, which was the file RCCUST attempted to 
access. The second and third addresses are BOO2,, and AFFCi.¢, 
respectively. Address BOO2,, points to the location into which 
the CUSTFIL record was to be read. As you can see, there is no 
record in this location since the GETUP was never accomplished. 
The third address, AFFCig, points to the location that contains 
the record key, F1F1F1F1F1. Both of these locations are in the 
user program area. 
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SINGLE AND MULTITHREAD SNAPS 


@ 9.9. SINGLE AND MULTITHREAD SNAPS 


Order of interface areas 


Different DSECTs 


There are two major differences between single-thread and 
multithread snap dumps. First, the order of the interface areas is 
different. In single-thread, it is: program information block; output 
message area; input message area; work area; continuity data 
area; and, defined record area. On multithread, it is: program 
information block; output message area; continuity data area; 
work area; input message area; and, defined record area. Since 
the allocation map in an edited dump points directly to these 
areas, there should be no difficulty in locating them in either 
single or multithread IMS. 


The second major difference concerns the thread control block. 
The format for single-thread and multithread is totally different. 
Figures 9-4 and 9-5 provide listings of the thread control block 
DSECTs for both single-thread and multithread IMS. You will see 
by examining these figures that although the format is different, 
the data they contain is basically the same. 
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LOCe 


goonoe 


S90n0c 
Soon0o 
900004 
890004 
Sqon0s 
000008 
So000Cc 
80000C 
900019 
Coanio 
P90014 
C90014 
590018 
Ogonis 
Sgonic 
GJoOOIC 
890020 
900029 
Qo001¢c 
fo0030 
So0036 
890034 
@90934 
fe0038 
caon3c 
Soon3c 
Scon4e 
Soon44 
toon4e 


300008 
Soano4 
loon02 
feon0! 


Ogcen4c 
doa0N4D 
fasn4D 09 
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LINE SOURCE STATEMENT 


A99794 


ZMaDTHCB 


69930+ZTSDTHCK DSECT 


BIIB +6 


B99B2+e¢ THREAD CONTROL BLOCK / SYSTEM INcORMATION BLOCK 


B9983+e 


B9I84ee THREAD CONTROL SECTIUN 


BIIBS+e 
BI9Bb+8 
b99BT+e 
B998B+e 
BOVAI+ZTSTPIBA 
BOIOVO+ZTHHPIBA 
BOPIFL+ZTRTIMA 
BIFIZ+ZTRHIMA 
B99I3Z+4+ZTATWA 
BOII4*+Z2TBHWA 
BOGY5+ZTRTOMA 
B9FI6+ZTRHOMA 
BIFIT+ZTBTCEA 
BODIB+ZTRHCDA 
BIOPIPSZTARTORMA 
BOOOO+ZT#HDKA 
BOCOL+ZTaD0KEC 
BOOO2+ZTHHDDRA 
BOCO3+ZTSSUBFL 
SOCCHY*+ZTRHDFA 
BOSOS+ZTaTF AM 
BOCGE+ZTAHFAM 
60507+ZTeHNUMF 
BOCOBS+ZTATATA 
6CCOP+ZTRHATA 
BOSLO+ZTRTPTA 
BOCILL+ZTSHPTA 
BOCI2+ZT#TPTA] 
BOCL3+ZTa@TTTA 
BOGI4+ZTaHTTAa 
BCOCIS+ZTR#HIOAY 
BCOLG+ZTRHPLA 
BOCI7+ZT#HRIQF 
BOCLEse 


INSERTED EQU°S Tu MATCH O5/7 NAMES 


twU 
OS 
EQuU 
US 
LQU 
OS 
Eau 
us 
tau 
vs 
ewWU 
us 
EQU 
DS 
Euu 
vs 
cau 
oS 
tw 
EQuU 
bs 
Eau 
vs 
us 
tuu 
vs 
US 
vs 
vs 


BOC Ys+e EQUATES 


380029+Zd8S0LSH 
6O021+Z88SOLAS 
n0l22+Z6eS0LCO 
4OC23+ZBRSOLST 
bOCL4+8 

BOC25+¢ZTBHAIQL 
dCOZ6+ZABUSER 
6CO2Z7+Z7TAUSER 
oCcCZbee 

BOC LI +8 


tQuU 
twu 
bQu 
tQu 


LS 
buy 
vc 


*m™s) N@#¢* De Pre pre rprerpe Pe 


PROGRAM INFORMATION BLOCK ADDR 
INPUT MESSAGE AREA ADDR 

WORK AREA ADDR 

OUTPUT MESSAGE ARea ALDOR 
CONTINUITY DATA AREA ADDR 
DEFINED KECORD ARta ADOR 

DATA DEFINITION RECORD ADDR 


DEFINED FILE/SUBFILE PKT ADOR 


4F FILE alLLOCATION taP 
eeZTHHFAM FILE ALLOCATION MAP LENGTH 


F 
. 


FOR 


ACTION CONTROL REC PTR 
PROG CONTROL TABLE REC PTR 
TERM CONTROL TAd KeEC PTR 
START OF VARIABLE I1/70 AREA 
PROGRAM LOAD AREA ADORESS 
BYPASS InTERRUPT QuEUE PTrk 


IST BYTE OF ZTHHBigP 


x*U8* SHUTDOWN IN PROCESS 

X*O4* AUTOMATIC STATUS 

x*02¢ ZZUP/7ZDWN COMMAND OUTSTANDING 
x*Ol* SHUTDOWN TIMEN 


xLI BYPASSED INTERRupT QuEut LENGTH 
* 


x* 


uu’ « USER FLAG 


MUST ALWAYS HE ON Oun BYTE DUUNDARY 


Figure 9-4. Single-thread Thread Control Block (Part 1 of 4) 























UP-9206 SPERRY UNIVAC C3s/3 


IMS ACTION PROGRAMMING IN RPG II 
SINGLE-THREAD THREAD CONTROL BLOCK 


9-15 


LIWE 
BOCI0+s 
bOC31+8 
BOC32+¢8 
BOC33+6 
BOC34e# 
BCO3ISe+ZT#TIND 
BNC364+ZTRHIND 
sOC37+8 
6OC3a+¢ 
BOC39+8 
BNCYO+Z TRH INSP 
oOCCH41L+ZTAH IT NkR 
BNC42+4+Z2TRHINOT 
6OC4%34+ZT&HINEO 
BOC4YH+ZTRHHINEX 
BOC4S*+ZIBHINCN 
BIOYH+7TRHINIR 
BOCY74+ZT#HI NUP 
BOC4YE+e 
BNOYD+ZTRHSYIND 
bOOSO+ZTHILIST 
bOchsl+ZTe8TGHRD 
bOC52+ZTRTRSD 
69553+4Z2ZTayUTOUT 
SOCS4+ZTRESETL 
BOTSS+ZTRBUSETKX 
BINS&6e4+Z7TH#ZZOPN 
bCCS7+ZTRPSSK 
BCTSASe 
BlNbF+® 
BOGb6 G+ 
bOlol+ZTAaTFC 
BICH2+ZTBHFC 
Blilojges 
BOG64+ZTRETUPDA 
89046542 TRHUPLA 
BND66+ZTRTCR 
HOG674+ZTSHRPLA 
SIC CKH+LT ATE WA tau 
sTI169+ZTAHE WA vS 34 FILE 1G5T wORK Angad 
BOT7C+ZTBOMSL uS A TCT ADUE OF DMS RUNTUNIT 
SIUGCTL+ZTROMCA LDS A YAS = OMCA ADDRESS 
boOo7T 2+ 
bOCT 3+ 
uUOCT4H4# 
beC7o+8 
non bee 


SOURCE STATEMENT 


1/0 HAS OCCURRED 
INITIAL SETTING FOR USER 
IMS ACTIVE 

COUNT FOR TOTA). 


Time 
OCan4eE 
OO0N4E 


EWU * 
vs XLL CONTROL INDICATURS 


EQUATES FOR ZTsHIND 
Coo0s9 
Cooo4e 
900020 
Co0910 
Coono4s 
Ocon04 
000002 
9c0001 


EQ@y 
twlt 
tG@u 
eQu 
eWU 
EGU 
tQu 
EQuU 


SNAP ENDICATON 

ERROn RETURN 

DELAYED INTERW,AL SUCCESSION 
EXPLICIT OuTPuTt 

EXTERNAL SUCCcCSSION 

CANCELLED 

INTERNAL REWUEST TO FILE MGMT 
UPDATE PERFORMED bY THIS ACTION 


xtsoe 
x*4oe 
x°20¢ 
x*1ce 
x*Uee 
x*ure 
x*u2e 
x*ule 


us 

twu 
tQu 
tQu 
bWU 
bay 
bad 
Buy 
0S 


XLI CONTROL INUICATURS 

x*oO0* INTEKRUPT LIST IF SET 

y'4Ne 6 4{F UN INDICATES READ FROM TOMFOLE 
X*20* « RESEND = NU 

X*1S* USER TIME OUT 

x*Ose 
x*O4e 
x*O20 
oF 


Coo004rF 
Coonan 
So0n40 
Oc0n20 
Ooo019 
"n0068 
90964 
Qoanc2 
feons3 


USE JHE TEXT 41, UMA ALTHUUGH TRANS Was CNC 
INUICATES TO wakITk ZZO0PN TERM. RECORD 
FILE MANAGEMENT ENTRIES 


Co0074 
f90074 


tw 


vs BYTE O 38 OF PARAUS 


BYTE 3 3 FUNCTION CODE 
So0n78 
290978 
Oean7Cc 
feco7c 
focnec 
ta9087 
Faanec 


ceoo9t 


EWU 
vs 
tad 
os 


JNPROTECTED OTF ADRK 


PARAM LIST AUDR 


SAVE AREAS 


T9C094 
tecovc 


sOG/77+¢Z1aHSAuin 
HOC7H+ZTRHSAlL A 
bIC7T9+# 
BNTKO+e 
rACal+e 


re) 
vS 


SYSTeM 


LaF 
LHF 


DATA 
INTERM AL REQUEST 


LuWFORMATION SeCTION 


MANAGCMENT CAVE AREA 


SAVE AREA 


Figure 9-4. Single-thread Thread Control Block (Part 2 of 4) 
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LOCe LINE SOURKCE STATEMENT 
000124 680C0824ZbaSTIDT US F TRANSACTION CODE T,BLE 
000128 s00834ZBasSACcT oS ACTION CONTROL TAbLE 
Co012C BOCB4+Zb8SFCT US PROGRAM CONTROL TABLE 
Co0130 vOOk8S5+ZeaSFCTI vs FILE CONTROL TaBbLtE INDEX 
000134 80086+Z62STERM US TERMINAL CNTL TBL ADDR 
000138 80987+ZB8#SNCTI OS DEF FILE CONTROL TABLE 
Co013C BN088+ZbASFADR US IMS LOAD ADORESS 
000149 wOOs89+ZHBSAVAL US AVAILABLE LIST ADDRESS 
000144 BO090+ZbaSTCS OS TERMe CONTROL SECTION 
Co0148 BNO91+ZBASIMB DS INPUT MESSAGE BUFFER 
O0014C BOOIZ2+ZBRSIOAE OS I1/Q AREA END ADDR 
COOISC BO093+ZBaSFSAD vS ADDR IMS SESSION STATISTICS 
000154 600944Z28aLOUTM LS LARGEST OUTPUT MSue 
000156 60095+ZB8LINM oS LARGEST INPUT mSGe 
000158 BO096+ZH2LOMT]T OS 4C LARGEST OUTPUT MSGe=TERM 1De NAME 
O001SC BO097+ZbaLIMTI US 4C LARGEST INPUT MSGe=TERM 1De NAME 
000160 BCO9e+ZbBSMLL OS H STANDARD MESSAGE LINE LENGTH 
900162 B00994+Z7BHSMNL US H STANDARD MESSAGE UMBER OF LINES 
000164 BG1904+ZBaSIMBL US H INPUT MESSAGE BUFFER LENGTH 
000166 sO101+Zb8eTMCCA OS H NUMBER OF TERMS Ili ICAM CCA 
000168 B8O102+2BaSTUF oS XL1 » USER TIMEOUT FLAG 
000169 KN103+ZHRSOLOF US xt 1 CONTROL INDICATURS FOR AUDIT 
BO1O4ee 
BOLIS+6 EWUATES FOR ZBaSOLUF 
OCO08N BO106+ZbHSOLUP EGU X*80* UPDATING PERMITTED 
900042 BwOrtd7+ZBeSOLAl EQU x*4O* AUDIT MODULE INCLUDED 
BOING+e (BEF IMAGES, TR Fitrs) 
000020 s6O0109+Z7usS50LKD EWU X*°20* ROLLBACK PROGKAM / FILE DOWN 
O90010 BO110+ZB#S0LSU EQU X*10* SUPPRESS UPDATES 
000008 sBollit+Z5#50LTB EQU x*O08* REFORE IMAGES TRACED 
OQ0N04 BoIl2+ZARSOLTA EWU x*O4e AFTER IMAGES tRACED 
000002 801134Z28#SOLT} EQu X'92* INPUT MESSAGES TRACED 
000001 BOLI4+ZBaSOLTE EQU X'O1* 1/70 ERROR TRACE FILE 
: HNL1LS+* 
@0016C 85116+ vs oF 
BOLIL7+® 
00016C SNII18+ZdR8FLGI DS X e« FLAG! UF STARTUP 
C000N82 BOLI9+ZbasTRIN X*8O* «© STARTUP ACTivE 
900040 60120+Z8RTCRSH X*40e e#TRCFILESCRASH 
BOOKZ2Z0 aANi21+ZBTEKT X'208 e#TRCFILESEXT 
900160 801224+ZBeFL G2 x eFLAG FOR TOMFILE 
Cn0n8sd o1f123+ZuaTOMUP x*oCt «© TOMFILE CONF ;GURED 
900001 b6O0124+Zba TOMER X*91l* ¢ ERROR ON TOM FILE 
000002 69125+ZG8TOMNT x*02* e¢ DO NOT TRACE TOMFILE 
OCOOI6E oO126+24HFLG3 X¥ eFLAG FOR TYPE OF QWESTART 
SCo0oCl AOL2Z7+ZRRTNDCL ATUL eSTARTECLEAN 
200002 HBOl24+ZBHINDWA x*O2¢ e¢STARTSWARM 
2e0004 BoOlz2g+ZbReENDCO x*O4* eSTARTSCOLD 
SOO16F 380130+Z7baFLG4Y x UMS FLAG BYTE 
800082 Bo1s14+2depNSDm X¥'80" IMS WAS MADE «a REQUEST TO OMS 
990040 HoL32+ZHBDFSDS x*40" DMS HAS TERMINATED 
O°0022 8f133+2baNMSRuU x*20% OMS KUN-UNIT LXISTS 


n 


rISMAAANARAT 





Figure 9-4. Single-thread Thread Contro! Block (Part 3 of 4) 
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LOCe 
Ovonl9 
Se0nGs 
000175 
Se0082 
0¢0049 
9900N25 
Goo000s 
C9004 
000171 
090174 
190178 
090017C 
900189 
990182 
000184 
000188 
@0018C 
f00199 
Ce0194 
900198 
Ceoi9c 
Seo1g9c 
00019¢ 
Oo0000 


LINE SOURCE 
BO134+Z25a1MSNA 
6C135*¢ZBRDMSNA 
BOL36+ZBRFLGS 
BCL37+ZB8KAT 
BOL3IB8+ZbaSTATS 
BCL3S9+ZBR8SFSEN 
8014O0+ZB8aG6LB 
BOL41+ZBa8DED 
BOLHY2¢ 
BO143+Z6#LPCT 
bO1444+ZBRL ACT 
BOLYS+ZB8LAD 
bO146+ZBRNLST 
BOLd7+ 
BOLYB+ZCBCCA 
BOLYS+ZCRLOCAP 
bO1LSO+ZHbRMDICE 
BCLS +ZbaUNvoEF 
6N1524¢76eDATE 
BCIS3+Z2be2SESLN 
BC1>44¢Z7Q8THFEIN 
b0155+ZTHHLEN 
BOLSé64+ZTRTLEN 
BI1LS7+ZCRIIP 
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STATEMENT 


EQU 
EQu 
vs 
cau 
tQu 
EWU 
E&U 
EQU 
bS 
oS 
DS 
vs 
os 
cS 
us 
vs 
vs 
us 
oS 
us 
os 
EQu 
EWU 
csect 





Figure 9-4. 


IMS 
DMS 


NOT ALLOWEn ACCESS TO OMS 
1S NOT THERE 


x*1oe 
x*ose 
xll 

x*aece 
x*4Ce 
x'2o¢ 


KATAK AWA CONFIGURED 

STATISTICS AT SHUTDOWN 

SFS ENABLED 

xX*O08* GLOBAL NETWORK 

X*04* DEDICATED NETRoRK 

XL3 UNUSED 

F LAST PCT ADDRESS 

F LAST ACT ADDRESS 

F LAST LOA AREA ADURESS 

H INTLIST#N VALUE 

XL2 UNUSED 

F CCA NAME 
LOCAP NAME 
OICESSCREEN CLEAR/.SG POSITION 
POINTER TO TRIDT to PROCESS UNDEF. TRANS eCOnES 
TODAY"S VATE 

F LENGTH#SESSION TAcLE@ZSTAT 

OF e THIS TAG MUST STAY aT END 

#-ZTRUTHCH LENGTH OF THC 

ZTSHLEN 


Single-thread Thread Control Block (Part 4 of 4) 
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@o0000 
Soo000 
co0004 
000008 
000009 
OoO00A 
DOOODA 
Coo00B 


Oo000c 
000010 
000014 
000018 
Oooo!c 
Coo0z2ze 
000024 
000028 
Oo002Cc 
Oo003¢ 
000034 
900020 
000054 
Coo0ss 
Oo005c 
000060 
000064 
000068 
Coo06c 
800074 


Sc0075 
090076 
Coon7s8 
COO07A 


LINE SOURCE 


2628 

2629 
A26304¢ZT#HOTHCE 
A2Z6314ZTRTHQPT 
A2632+ZTAaNTHCS 
A2633¢ZTRTHURF 
A2634¢ZTSTHRDE 
A2635+ZTHQWAILT 
A26364ZT#REGRS 
A2637¢ZT#IECK3 
A2638e8 
A263948 
A2640 +8 
A2641*ZTRTHSVR 
A26424¢ZTBTHRAD 
A2Z26434ZTSBTPIBA 
AZ2644+ZTATIMA 
AZ264S*+ZTRIWA 
A2646eZTSTOMA 
AZO474¢ZTRTCDA 
A2E4B*ZTHTDRMA 
A2Z2649*+ZTRDOREC 
A26504ZT8SUBFL 
A2651¢ZTRTFAM 
A26924ZTS#TNUMEF 
A2Z6S3ZTMTATA 
A26S4eZTRTPTA 
A26554¢ZTRTPTAL 
A2Z6S64ZTRITTA 
A2657+Z2T8TIMB 
A2656¢ZT#TEDIT 
A26594ZTRTRID 
A26604ZTSTINO 
A2661¢8 
A2662+8 
A2663+8 
A2664%48 
A2665+¢4 
A2b6648 
A2667+8 
A2668e8 
A2b669e8 
A267008 
A267) +8 
A2b72+¢ 

A267 348 
A267448 
AZ6754¢ZT&RTERS 
A26744ZTBTES 
A2677+ZCRSFSSC 
AZ678+ZCHITLN 


STaTEMENT 


PRINT GEN 
ZMnDTHCB 
DSECT 
os F NEXT THREAD IN QUEUE POINTER 
vs F NEXT THREAD FOR SCHEDULING 
bs x URGENT FLAG 0 = ROUTINE 
vs x THREAD READY FLAG 1 = READY 
DS OX BIT O INITIAL THREAD WAIT FLAG = wAIT 
ps X BIT 7 RESTORE REGISTER FLAG O - yES 
DS x BIT O CANCEL FLAG 1 © CANCEL 
BIT 2 OUTPUT MESSAGE GENERATED By 7G8MTHSO 
BIT 3 INTERNAL CANCEL INITIATED 
bIT 7 TECK FLAG 1 = 3worD 
F e THREAD SAVE AREA REGISTER 
F e THREAD RETURN AUnRESS 
A PROGRAM INFORMATION BLOCK ADDR 
A INPUT MESSAGE AREA ADOR 
A WORK AREA ADDR 
A OUTPUT MESSAGE ARE ADDR 
A 
A 
A 
A 


CONTINUITY DATA AngA ADDR 
DEFINED RECORD AREA ADDR 
DATA DEFINITION RECORD ADDR 
OEFINED FILE SUBeFILE DESC ADDR 
AF FILE ALLOCATION maP 
eoZTaTFAM FILE ALLOCATION MAP LENGTH 
A ACTION CUNTROL TAvLE RECORD ADOR 
PROGRAM CONTROL TABLE RECORD ADDR 


TERMINAL CONTROL TABLE RECORD ADbDR 
INPUT MSG BUFFER aDDR 

A EDIT TABLE ADOR 

CL& TRANSACTION ID 

XLT CONTROL INOICATuURS 

BIT 3 TERMINATION TYPE 


A 
F 
A 
A 


0 NORMAL 

i ABNORMAL 

rt) NO 

! YES 

Bit 3-4 INTERNAL MESSAGE CONTROL: 
oo END ACTION oR END TrANSACTION 
ol EXPLICIT OuTPUT 
10 DELAYED INTERNAL SUcCESSION 
11 CANCELLED 

81T 5 INTERNAL REQUEST INDIC FoR FM 

a) NO 

1 YES 


vIT 2 ERROR RETURN 


bIT 6 OUTPUT IN PROCESS 
bolT 7 OUIPUT WAITED 
X ERROR COLE NUMBER 
H RELATIVE ACT RECOnn ADDR 
H INPUT STATUS BYTE COUNT 
xL1 xTIOw FLO LEN CIR@INVALID TRANSACTION 





Figure 9-5. Multithread Thread Control Block (Part 1 of 2) 
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LOCe 
€00078 


Co0084 
Co00se 
Coo0sc 


000099 
Co0094 


oc0078 
O000A4 
Oo0000 
Coo000 
Oooor 8 
OOO0oFC 
000118 
000166 
00018C 
Cooiee 
090184 
000188 
600188 
So0040 
Ooo004 
S90001 
0001BC 
doo1Cce 
Ooo1c4 
to01¢8 
0c01c8 
200000 


LINE 
A2679+ZC8SFSID OS 


SOURCE STATEMENT 


CLé& SUCCESSOR=ID FORK REBUILD 


A2680+8 FILE MANAGEMENT ENTRIES 

PARAMETER LIST FOR SUBTASK 

A BEGIN ADDR 

A REQUEST PARAM LIST ADDR 

IN LIST 

BYTE 3 = FUNCTION COnE 


A2681+¢4 
A2Z682+ZTRTBA os 
A2683+ZTRTRPLA DS 
A26844ZTRIFC vs 
A2695+e 
A2Z686eZTRTUPDA US 
A2687+ZTRTCR oS 
A2688+e OTHER 
A26894+ZTRTFWA 0S 
A246904Z2TRBTSAVI DS 
A2Z6914ZTRTSAV2 US 
AZ26924¢ZT8SAVS ERU 
A2Z6934ZTHSAVES EQU 
A26944 vs 
AZ269S+ZTHTSAV4 US 
A26964+ZTHTSAV]Z US 
A26974+ZARPSSK 0S 
A2Z69B+ZTRTFLA os 
AZE9F+ZTRITF IL bs 
A27004ZT#TF2 os 
A2701+¢Z2T#SYIND EQU 
A2702¢ZT#TOMRD EQU 
A27034ZTRZZ0PN EQU 
A2704¢ZT#RDOF Ewu 
A27G5+ZTRUDMCA OS 
A279064ZT#IOUMCA US 
A27074¢ZT8SIBA US 
A2708+ vs 
A27094¢ZTHTLEN EQu 


A2710+ZO#QUTMT CSECT 





Figure 9-5. 


A BYTE O - & OF PARAKWS 


A UNPROTECTED DTF AunR 
A COVER REG 


3A WORK AREA 

11A SAVE AREA 1 

11A 

ZTBTSAVZ SAVE AREA 5 

ZT#8Sav5+40 

7F*Oe 

18A SAVE AREA 4 

11A SAVE AREA 3 

oF 

F REQUIRED BY IRAM 

F APPL eMANAGe 

F FLAG BYTE 

ZT#TF2Z FLAGS 

X*40* INDICATES TOM ,EAD . 
x*O4" INDICATES TO wRITE ZZOPN TERM. RECORD 
X*O1L* MIRAM RE*READ FLAG 

A USER PROGRAM DMCA ADDRESS 

A IMS INTERNAL OMCA ADDRESS 

F SI ADORESS 

OF 

e-ZTexOTHCB LENGTH OF CONTROL BLOCK 


Multithread Thread Control Block (Part 2 of 2) 
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TERMINAL CONTROL TABLE 


Terminal control table 


LOCe 


900000 


co0000 
Oco004 
Co000s8 
Poo00c 
Sooo0lc 
000014 
Go0nl8 
QOO0I1A 
000018 
000018 


Coo0se 
Ooo04e 
Coo020 
Oo00!10 
000008 
Cooo04 
Oo0n02 
000001 
So0001 


Goonic 


Cocoac 
Soo04e 
Q00020 
990010 
090008 
Coo004 
eo0002 
Coo00! 


Bo0c10 
CeonlD 


Seoose 
Scan4o 
fo0022 
Soonic 
Coon08 


Co0004 
Seonc2 
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valuable debugging aid. Figure 9-6 shows this table. 


LINE SOURCE 


2712 
A2713+ZCRDOTCT 
A271 440 
A27154¢ZC8LINK 
A2716+ZC#TID 
A27\74ZC#TAL 
A271 B+ZCRTALT 
A2719+ZCATTTA 
A2720¢ZC#HTESR 
A27214ZC#TCOL 
A2722+¢ZCBTLN 
A2723+7ZCR#TTST 
A27244ZCATST 
A2725+8 
A2726+¢* 
A2727+8 
A2728+ZC8TILST 
A2729¢ZCATTIMD 
A27304ZC#TTUM 
A27314ZC8TTOWN 
A27324¢ZC#TTHLD 
A2733¢ZC8TTUT 
A2734+ZCHTMWR 
A2735¢ZCHTMTC 
A2736¢ZCB8TOMW 
A2737+¢4 
A2738+ZCH#TSTI 
A27394¢ 
A274O0 +8 
A2741 46 
A2742+ZCHRTTIM 
A27434ZCaTITMT 
A27T44*#ZCRTALTS 
A274S eZ CHTTRCE 
A27464ZCBTTMWS 
A27474+ZC#8TTBTH 
A274B+ZC8TTRP 
A2749+ZCHTTMS 
A2750+¢8 
A275i¢ZCaTST2 
A2Z27524+ZC#TPRSEF 
A2753+¢ 
A27S54+e 
A2755+¢6 
A27964¢ZCH#TTUNS 
A27374ZC8TTREL 
A27584+Z2CR82TPRMG 
A27S94Z7CRTERMP 
A27T604ZCRTTSTA 
A27T614¢2ZCRTCONT 
AZ2762¢ZC#TDELN 


STATEMENT 


ZMRDTCT 


DSECT 


os 
oS 
oS 
bs 
os 
os 
oS 
os 
vs 
eQy 


EQu 
E@u 
bwu 
EQu 
EWU 
EQuU 
EQU 
EQuU 
EQU 


EQuU 


EQu 
eQu 
EQuU 
bQ@u 
EQuU 
EQuU 
tau 
EQU 


EWwu 
bau 


wu 
EQu 
EQU 
bau 
eau 
EWU 
EWU 


eee 


F ACT 


TERMINAL CONTraL TABLE RECORD etee 


LINK To NEXT TcT IN QUEUE 


XL4 TERMINAL ID 


F REL ADDR SOURCE TCT 


(0S/3) 


F REL ADOR ALTERNATE TCT (0S/3) 

F CORRESPONDING TTT aDURESS 

F SuCC ACT REL ADOR = ROLLBACK 
CONTINUITY DATA LENGTH 

XL1 LINE NUMBER 

xL7 STATUS BYTES 

zZCaTTstT 


x*s8oe 
x*40e 
x*20° 
x*10¢ 
x*Gse 
x*O4e 
x*'O2e 
x*Ore 
x*ole 


EQUATES FOR ZCHTTST/ZcaTst 


LAST TCT 
TEST MODE 

URGENT MESSAGE, ACTION 

TERMINAL DOWN 

HOLD TERMINAL 

URGENT TERMINAy 

MSG wAIT (FOR ZZTST) RECEIVED 
MWRITE FOR ZZTST (SINLGE THREay) 
OUTSTANDING MwRITE (MULTI THREAD) 


ZCHeTsSTel,l 


x*'8Oe 
x*4Or 
x*20° 
x*1o¢ 
x*O8e 
x*o4de 
x'O2¢* 
x*ol1e 


EQUATES FOR ZC#7STl 


INTERACTIVE MUDE 

MASTER TERMINAL 
ALTERNATE TERM SPECIFIED 
ROLLBACK COMPLETE 

IMS SENT MSG walT 

BATCH TERMINAL 

ROLLBACK IN PROCESS 

MSG 10 ORIG TERM SENT 


ZCBTSTI+i gi 
ZCRTST2 


x*'ace 
x'4oe 
x*20¢e 
x*108 
x*O8* 
x*o4ue 
x"*O2e 


FQ@UATES FOR ZCaTST2 


MWRKITE ISSUED FROM ZOBUNSMT MODULE 
RELEASE BUFFEn AT MWRITE COMPL 

MSG IN QUEVE 

MSG IN PROCESS 

SEND AUTO STATS MESSAGE 
CONTINUOUS OUIPUT REQUESTED 

DEL NOTICE - acTION To BE SCHED 


Figure 9-6. Single-thread and Multithread Terminal Control Table (Part 1 of 5) 





9-20 


The terminal control table for single and multithread IMS is also a 
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LOCe 
000001 


GOOOIE 


fo008e 
000040 
Coc0z20 
000010 
Coo00s 
090004 
On0002 
900001 


SooolFr 


Cooose 
Coco040 
000020 
Oo00!0 
Coo008 
Go00004 


600002 
Ooo001 


000020 


Ooo080 
Coo040 
Oo004%C 
090020 
0000290 
Ooo00!0 
Cooo0s 
Co0c04 
Oo0008 
Coooc4 
000002 
Co0001 


900021 


Ocoose 
Oco04e 


LINE 
A276342C#TOIQ 
A2764+8 
A2765¢ZC#8TST3 
A276648 
A2767+8 
A2768+8 
AZ2769*ZC8TTOR 
A2770*4ZC8TTQNE 
A2771¢ZCRTHDRS 
A2772+ZC#8TIDON 
A2773+ZCRTIGM 
A2774*¢#ZCRCOIP 
A2775*+ZCHINRDY 
A2776+ZCBTUNAC 
A2777 8 
A2778+8 
A2779*ZCHTST4Y 
A2780+8 
A278) +8 
A2782+8 
AZ27B34Z2CHERMEX 
A27B844¢ZCBSFSRE 
A278S¢ZCBABTDY 
A2786+ZCA8DYTWD 
A2787+ZCRSIGN 
A2788+72CHATTRI 
A27894ZC8CONSL 
A27904¢ZC8CNTRD 
A279 148 
A2792¢ZCHTSTS 
A279348 
A27T94+0@ 
A2795+¢8 
A27964ZCHIMPRI 
A2797+ZCR8DEPND 
A279B84ZCADEPRT 
A27994ZCB8OMSUP 
A2800+ZC8BND 
A28014¢ZCRUBPND 
A2802+¢ZCROMSRO 
A28934ZCR8DMSUB 
A2854+ZC#UPDRU 
A2605+¢Z7CayPDTD 
A2B9064ZCHTCALL 
A2807+ZC#DMSDR 
A2808+e8 
AZ2BO094+ZCH#TSTS 
A2610+8 
A281l1+*8 
A7812+@ 
A2813+ZCHOMSER EQu 
A25144+ZCB8WRKI EGU 


EQU 
buy 
EQUATES 


EQU 
EQu 
EQu 
Ewu 
EQU 
EQU 
EQU 
EQu 


EQU 
EQUATES 


EQu 
EQuU 
Eq@u 
£@U 
EQuU 
Eau 
EQuU 
Ewu 


Eau 
EQUATES 


EQU 
EWU 
EQu 
EQU 
EQU 
EQU 
EQuU 
equ 
bQu 
bau 
EWU 
EQU 


EWU 


EQUATES 


SOURCE STATEMENT 


x*Ope 


OUTPUT GENERATED FOR INPUT QUEUING 


ZCRTST24i 51 


FOR ZCxHTST3 


x*60% 
x*4Q0° 
x*20° 
x*1o°e 
x*oes 
x*O4e 
x*O2e 
x*O1e 


DISCONNECT REWUESTED (S/T) 
TERMINAL*S LOw QUEUE NOT EMPTy 
OUTPUT HEADER cAVED 
INTERNAL DELIVERY NOTICE 
IMS GENERATED ERROR MSG 
CONTINUOUS OUTPUT IN PROCESS (m/T) 
NO ImS READY MSG TO THIS TERMINAL 
SEND UNSOLICITED OUTPUT INDICATOR 
FOR SWITCHED MESSAGES at ACTION END 


ZCRTST3+1 51 


FOR ZCaTST4 


x*8or 
x*40° 
x*20° 
x*10° 
x*O8e 
x*O4e 
x*O2* 
x*Ole 


ZCOBTST44+1 91 


A/mM GENERATED ERROR MSGe 

REBUILD ALLOWED By A/P 

ABORT DYNAMIC SESSION 

ABORT TERM WINDOW 

SIGN ON FOR DYNAMIC SESSION 

TERM HAS CONFIGe ATTRIBUTES 

CONSOLE TERMINAL 

OUTSTANDING TCS/UISKETTE READ FUNCTION 


OMS FLAULS 


FOR ZC#TSTS 


x*8ore 
x*4or 
x*4or 
x*2o° 
x"20° 
x*108 
x*Obe 
x*G4e 
x*O6e 
x*O4e 
x*O2¢ 
x°Ole 


IMPACT FOR ACTION 

PENDING 

ACTIUN ISSUED nEPART 

ISSUED DSM OPceN FOR UPDATE 
BOUND/UNBOUND STATE 

UNBIND PENDING 

OMS FORCED DErART wITH ROLLBACK 
DMS KUN UNIT UNBOUND 

OPENED FOR UPUVATE IN THIS RUN-UNIT 
UPDATING RUN@*UNIT IN THIS SUCCESS UNIT 
FUNCTION CALL/TERMINATION CALL 

OMS REQUEST VIA DeReMe 


ISSUED 
DEPART 


ZCaTstTS+15)] OMS FLAGS EXTENSION 


FOR ZCHTST6 


x*soe 
x*40O° 





DMS ERROR IN KUN@UNIT 
TEMPORAKY FLAG &] 


Figure 9-6. Single-thread and Multithread Terminal Control Table (Part 2 of 5) 
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TERMINAL CONTROL TABLE 


LOCe 
000020 
000010 


000080 
Coo0040 
990020 
000010 


000023 


Goo0D9 


0000C! 
So00Cc3 
Cooocs 


Co0024 


000080 
O90040 
900020 
So00Ic 
Soo008 


000025 


090026 
8co026 
Gcon2c 
Oco030 
690034 
0c0036 
000037 
000038 
Cooo3a 
teo003c 


LINE SOURCE STATEMENT 

A28iS*ZC#WRK2 E@u x°20* TEMPORARY FLAG 8&2 
AZBlLGe¢ZCRTTMDOF EQuU x'iO* MOEFER ISSUED -OR THIS TERMINAL 
A2817+® THE FOLLOWING STATUS BYTE TAGS ARE NOT CLEARED WHEN A Gi OBAL 
A28l8¢® NETWORK DYNAMIC TERMINAL DOES A sSSOFF 
A2819+¢8 ZCaTTLst 

A2B820e8 ZCaTTUT 

A2821+¢8 ZCaTIMtT 

A2822+0 ZCRTNRDOY 

A282308 ZCaTUNAC 

A2824e6 ZCRATTRI 

A2B25+¢ 

A2826+8 

A2827+ZCRD0OPST OS xX ODP STATUS BYTE 

A2B2u+6 

A2B29e8 EQUATES FOR ZCxDDPST 

A2B30e8 

A2B8314+ZCB8REMTR EQU x*80* REMOTE TRANS 
A2832¢ZCB8FSOUT EQu x*40¢ FINO SESSION uiTSTANDING 
A28334¢Z2CBPSEDO EGu x*26* PSEUDO TCT 
AZ2834+ZCaDDPOT Eau x°10¢ MwRITE FOR DOP 

A2835¢8 

A28364ZCRDDPMD US x DOP MODE 

A2837+8 

A2838e8¢ EQUATES FOR ZCwDOP MODE 

A283948 

AZ2B4O+ZCBOTR tau C*kK* DIRECTORY TRANSe ROUTING 
A2841+Z7CBPTRA EQU C*A* PROGRAM TRANSe ROUTING = ACTIVATE 
A26424+ZCRPTRC EQu C*C* PROGRAM TRANS. ROUTING = ABORT/CANCEL 
AZ843+ZCSPTHE EQU C*E* PROGRAM TRANS.» ROUTING = END 
A2B44ee 

A2B4S*+ZCHSFLAG OS XL1 GENERAL SFS FLAG BYTE 
A?B46e8 

A2847+e EQUATES FOR ZCaSFLAG 

A2B848e8 

A2ZB49+ZCHINFMT Euy x*8C® INPUT FORMAT 
A2B8SO4+¢ZCADYNM EQU X*46¢ DYNAMIC MEMORY 
A28514+ZC8SFBTI EQuU x*20° SFS FLAG } 

A2852+ZCHLTCF EQuU x*1O* INVALID XTION 
A2853¢ZC#SFBT2 EGU x*O08* SFS FLAG 2 

A2854e¢ 

AZ2BSS+ZCRSFIRC US xLl SFS INPUT RETRY -OUNT 
A2856+8 

A2a57+ os xL2 UNUSED 

A2858*ZC8TRCTA LS A TRCT ADOR 

A28594+2C8TQE os F CANCEL LINK 

A2B604ZCRPRFT US F DISFL TO PROCESS FILE TABLE 
A286i1+ZCHPQCNT OS H PROCESS yUEVE COUNT 
A2862+ZCAMQCNT OS XLI LAST ICAM SVC 
A26634ZCRTDELS US XL} DELIVERY NOTICE sTATUS 
AZ2B64*+ZCBLGCNT DS H LOw QUEUE COUNT 

A25654Z7CR8TIN H TOTAL INPUT COUNT 
A28664+ZCUTINT H TRANSe INPUT COUNT 





Figure 9-6. Single-thread and Multithread Terminal Control Table (Part 3 of 5) 
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TERMINAL CONTROL TABLE 


LOCe LINE SOURCE STATEMENT 

TQ003E A286747C8TTCM OS H TERM COMMAND COUNT 

So004#l 8 A286B+ZCHTINCH DS TOTAL NOe INPUT CUARSe 

CO0044 A2B8694+ZCHTOTCH OC TOTAL NOs OUTPUT CHARS. 

Co004%8 A2B704+ZCHTOC vs TOTAL OUTPUT COUNT 

COOD4A A28714+ZCHTOMSZ DS SOURCE TERM O/P MSGe SIZE 

COO04C = A28724ZCHTON vs TIMER LIwk 

GO005O 3 A28734¢ZCHIML vs INPUT MESSAGE LENGTH 

Co0052 A28744+ZCROML bs OUTPUT MESSAGE LENGTH 

O00054 A2875+ZC#TML os H TIMER MESSAGE LENGTH (05/3 MeTe) 
A2876+8 OS/3 Sete USES ZCB8COSEQ INSTEAL OF Z2CRTML 

CO0054 A28774+ZCRCOSEW EQu ZCaTmt C/O SEW COUNT (05/3 SeTe ONLY) 

00056 A2878+ZC#DML os H DDP MSGe LENGTH 

000058 A28794+Z7CHIBF vs INPUT BUFFER ADOK 

O0005C A2880+7C#0RF os OUTFUT BUFFER AUDK 

900060 A2881+ZCaTBF vs TIMER BUFFER ADDA 

090064 A7as82+7CHDBF vs DOP BUFFER Aa0Dn 

CO0N68 A2B83+ZCHDPREL OS A DDP BUFFER RELEASt ADDR 

Co006C A2B884+7C#HTDELC DS XL4 USER CONTINUOUS ,UTPUT CODE 

O00070 A2B88S4+ZCHSFSTC OS A SFS TERMINAL CLASS ENTRY ADOR 

CO0074 A28864+ZCBSFSFN US CL8 SFS FORMAT NAME 

OCO07C A28874+ZCRSESAD LS A SESSION STAT TABLt ADDR 

Co008D A288B+ZCRSESID DS F SESSION 10 

CO0084 A28894+ZCRTDMEM US F SFS DYNAMIC MEMORY ADOR 

800088 A28904ZCHTTRID DS CL8 TRANS 1D CINITIA, DATE/TIME) 

Oo008S A2h91+ZCRTRID Eay ZCRBTTRID OS/4 TAG 

800090 A28924+ZCROLCNT US H IMC DEADLOCK DETECTION COUNT 

000092 A2893+ bs H UNUSED 

Co0094 Az289744+ZCH8TCH bs A THREAD CONTROL BLUCK ADDR 

000098 A2a95+47CHTLI vs 8F TRANS LOCK INDICATOR 

O900B8 A28964ZCBTAUM OS 8F AUDITED UPDATE MaP 
A2597+e0@ ZCHTLI] AND ZCBTAUM MUST AGREE arTH ZTH&TNUMF IN THE THCB 

O90008 A28984+ZCBTTEXT US CL8 TRANSLaTED TERM CMU/TRANS CODE 

OCO0008 A28994+ZCHTCODE EQU ZCRTTEXT OS/4 TAG 

COODED A29004+ZCRTDDRC OS CL1 DDR NAME 10 CHAN (HIGH BYTE @ xtene) 
A29C1l¢#es THE ABOVE FIELD IS DEFINED IN Ucg/4 BUT NOT TAGGED 

SOODEL A2902+4Z2C#TDURN OS CL7 DATA DEF REC NAtiF 

OCODES A2903+ZCHTDFN US CL7 DEFINED FILE NAnE 

CQDDEF A2904+ os x UNUSED 

COOOFG A2995+ZCRTES us F SUCC ACT RECORD RELATIVE ADDR 
A2904e8 MULTI=THREAD SYSTEMS USE 7ZCHrs & ZCHCDC IN PLACE OF zcaTEs 

OO00FD A2997+ ORG ZCRTES 

GOOOFO A29084+7ZCHES vs H SUCC ACT RECORD Rit ATIVE ADDR 

COOOF2 A2909472CHCOL vs H CONTINUITY DATA Le NGTH 
A2910e8 

‘COOOF4Y A291L14+ZCHawWAl vs H WORK AREA INC 

COOOFS Az912+zZCHCOL LS nt CONTINUITY DATA ANEA INC 

OQOOFS A29134Z2C8TTIN DUS XLT TCT RECORD NUMBER 

CQOOF9 A2914+ vs xL1 UNUSED 

COOOFA A2915¢ vs H UNUSED 
A291 648 MULTI=THREAD YSES ZCHCDK & ZCHCES INSTEAD OF 7CaTTTIN 6, ZCHTINT 

DQOOFS A2917+ ORG ZCaTTIN 

COOOFS A291 8+ZCRCOK vs H TCT RECORD NUMBER 





Figure 9-6. Single-thread and Multithread Terminal Control Table (Part 4 of 5) 
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TERMINAL CONTROL TABLE 


LOCe 
OOOOFA 
Go00rFC 


000100 
000100 
000100 
000100 
000104 
000106 
000108 
OOO10A 


Q0010C 
000110 
Ooo110 
000111 
000112 


Oo0000 
Oo0080 
900040 
000020 
000010 
Oon00e 
000004 
Oo00002 


600113 


Co0080 
Oo004%0 
000020 
900010 
000008 
So0004 


000114 
000118 
Seoric 
000120 
Co012c 
Gooo00 


LINE SOURCE STATEMENT 

A29194ZC8CES os 4 SUCC ACT REL ADDR ~ ROLLBACK 
A29Z204¢ZCHSCFR OS XxL4 COUNT FIELD FOR ROLLBACK 
A292, +8 

A2922¢Z2C8TTIR DS XL1 TERM IND FOR ACTION PROG USING ROLLBACK 
A29234ZCHTIR EQu ZCaTTIR oS/4 TAG 

A29244 ORG ZCRTIR 

A2925¢ZCHTRWA DS TRACE WORK AREA 

A2926¢ZCBFBPA OS * FIRST BLOCK OF FaRTITION 
A2Z927+ZCRCBPA OS @® CURRENTLY ACCESSED BLOCK 
A292Z28+ZCB8LBPA US * LAST BLOCK OF ParRTITION 
A2929+ZCB8NRBCB DS @ OF REMeBYTES It CURRe BLOCK 
A293008 

A2931¢ZCBTLNAM DS CL4 LINE NAME 

A2932¢ZCRTCHAR DS CL4 TERMINAL CHARACTERISTICS 
A29334ZCHTTSL EQu ZCBTCHAR SCREEN LENGTH 
A2934+ZCHTTSW EQU ZC#TTSL+} SCREEN WIULTH 
A2935*+ZCRTTTYP EQu ZCaTTSWe) TERMINAL TYPE 

A293 6¢0 

A2937+8 EQUATES FOR ZCuTTTYP 

A2938+¢8 

A2939+ZCHTINFC Eau x*00* ULOO/UZ00/UTSIA/TTY 
A2Z94O*+ZCHTTYPR EQU x*8O* UTS4O0 PR 

A29414¢ZCBTT4YUZ2 EQU x*40* UTS4O90 CP (U2 mODE) 
A29424¢ZCHTTHUY EQU x*20* UTS4O00 CP (U4 MODE) OR UTS400 
A2943¢ZC8TT327 EQu x*10* JBM 3271 

A2Z944eZCHTTUIC EQU x*O8* UTS4O 

A294S4ZC#TTUZ0 EQu x*O04¢ UTS20 

A2946eZCHTT4HOT EWU x*02* UTS4YOO TEXT EvyTOR 

A2947 +0 

A294B*ZCHTTATT EQu ZCRBTTTYP+] TERMINAL ATTRIBUTES 
A2949e8 

A2950+8 EQUATES FOR ZCuTTATT 

A2951 + 

A2Z952¢ZCB8TTKAN EQU x*8O0* KATAKANA 

A29534¢ZCHTTINVI EGu x*40* NON@VIDEO 

A29S44+ZCRBTTSBT EQU x*20¢ SCREEN BYPASS 
A29S5¢ZC#TTPKT EQU x*10" PACKET PON TEnmMINAL 
A2Z956¢ZCHTTCST EQU x*O8* CIRCUIT SWITCH PON TERMINAL 
A29574*ZCRTTCCT EQu x*O4* TERMINAL ON CLUSTER CONTROLLER 
A2956e8 

A29594ZCR8TINER US F SFS ERROK FIELD 
A29604ZCHTRIDA DS A PTR TO TRIDT ENTRY FOR CURRENT TRANSACTION 
A29761+#ZC#ALTID OS F ALTERNATE TERM 10 
A29624¢ZCHTFIN US OF THIS MUST ALWAYS aE AT END 
AZ9634ZCRTLEN e-ZCHOTCT 
AZ9644+Z080UTMT 





Figure 9-6. Single-thread and Multithread Terminal Control Table (Part 5 of 5) 
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LINK MAP 


9.10. OTHER DEBUGGING RESOURCES 


Link map and symbol 
table 


Module RCCUST and 
P?IMSO00 


Module ZF#LINK 


Module P?SERIAL 


Module P?SPLOOO and 
P?IMSIXO 


Module P?IMSEQO and 
P?IMSDOO 


*ERROR field 


To find the cause of an action program snap dump requires the 
use of both the snap dump and user action program compile and 
link. Very briefly, we'd like to point out data in the link map and 
symbol table of your action program useful in debugging. Figures 
9-7 and 9-8 show the link map and symbol table for RCCUST. 


Looking at Figure 9-7, the first object module is RCCUST and its 
Ink-org is 0. Following RCCUST is P?IMSOOO. This object module 
handles initiation and termination procedures for the action 
program. It also handles communication between the program 
and the interface areas. Its Ink-org is 12A0. 


The third object module is ZF#LINK. This module provides the 
interface between action program function calls and IMS. Its 
Ink-org is 14F8. 


The object module P?SERIAL is responsible for making the RPG II 
action program serially reusable. It clears all switches and 
indicators prior to an action program getting control. However, 
the RPG Il programmer must reset all fields and arrays prior to 
program execution. The important point to remember is that RPG 
1 action programs must be serially reusable since IMS doesn’t 
reload a program if it’s already in main storage. 


The next two object modules included in Figure 9-7 are 
P?SPLOOO and P?IMSIXO. They provide I/O interfaces between 
IMS and the RPG II action program. P?SPLOOO handles all general 
|/O interface needs and P?IMSIXO handles all requests to indexed 
files. 


Two other object modules not present in Figure 9-7 but which 
could have been included are: P?IMSEQO, which handles 
sequential file requests; and P?IMSDOO, which handles DAM file 
requests. Which modules are actually included depends upon the 
specific |/O design of the action program. 


Figure 9-8 shows the symbol table for RCCUST. The important 
data it contains is the location of *ERROR at relative location 
1BO. 
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UNIVAC SYSTEM OS/3 LINKAGE EDITOR 
DATE= 81/04/07 


CONTROL STREAM ENCOUNTERED 


*EMREDDEDe 
@EMBEDDEDe 
*EMREDDED® 
*EMBEDDEDe 
SEMREDDFDe 


SYMAOLes 


ADOKY 
CLOSE 
DELKY 
ENOCRL 
FIND 
GETLOAD 
IMA 
KESRES 
OPEN 
P?IMA 
P20MA 
P?SPLO00 
RCCusTt 
RDIDCL 
ROKEYC 
RoKy!I 
ROSOC 
RDSQIC 
ROSRC 
REBYILD 
SEND 
SNAP 
STCRL 
SUBPROG 
XR3TMS 


PHASE NAME 


RCCUSTOO 


at 
‘8 


TRANS ADOR 


TIME] 


PARAM 


PHAS 


ROOT 
ROOT 
ROOT 
RooT 
ROOT 
ROOT 
RooT 
abs 

Root 
RooT 
root 
root 
ROOT 
ROOT 
ROOT 
RooT 
Root 
Root 
RooT 
Root 
rRooT 
rRoorT 
RoorT 
RooY 
RooT 


NODE « 


10.36 


OuUTeLoD 


LOadm accusT 


INCLUDE 
INCLUDE 
INCLUDE 
INCLUDE 
INCLUDE 
INCLUDE 


000018A4 
Oooolvic 
00001648 
Ooo01 soc 
00001920 
Co001s¢a 
CooncDis 
Oooo!F ea 
00001916 
00001764 
0000150€ 
000019E0 
000900000 
00001920 
00001890 
0000188¢ 
Ooo0191¢ 
Ooonlees 
GoooIelo 
00001890 
00001924 
00001 BE4 
00001808 
000018A0 
0o001894 


LOAD MODULE ~ 


Root 


ADDRESS» 


FLAG 


RCCUST 
P7IMSO00,SYSOBY 
ZFaLINK ,SYSOBV 
P?SERITAL »SYSOBY 
P?SPLO00,SYSOBY 
P7IMSIxXO,SYSOBS 


eDEFINITIONS 


Symaou 


ARETUR 
CMORB 
DLAOR 
€stre 
FREE 
GETUP 
INSERT 
LNKcP 
OPENF 
P2IMSE 
P?P16 
Pie 
ROlID 
ROTOL 
ROKEYC 
ROKYIC 
ROSQOCL 
Rosa. 
ROSACL 
RELREC 
SETL 
SSLOCK 
STumt 
UNLOCK 
TFSLIN 


RCCUST 
LABEL 


eee START OF AUTO*INCLUDED ELEMENTS = 
eee END OF AUTO@INCLUDED ELEMENTS = 
= 81/04/07 10635 ~ 


c 


t 


- 80/05/28 1%642 «© 


= 80/02/09 23603 - 


RCCUST 
RccusT 
Ima 
OMA 
Pls 


P?1Msoco 
P?1mMS000 
P7ONA 
P?IMA 
P?CDA 
P?P16 
ZFeLINK 
ZFaLINK 
XRSINS 
BUILD 
REBUILD 
GET 
GETUP 
Pur 
DELETE 
INSERT 
SETL 
Esere 
FREE 
RELREC 
UNLOCK 
OPEN 
CLOSE 
FINO 
SENO 
RETURN 
ARETURN 
SNAP 


AND PROCESSED AS FOLLOWS- 


. TyPE. 


nN ENTRY 
Entry 
ENTRY 
Entry 
ENTRY 
ENTRY 
ENTRY 
Entry 
ENTRY 
Csect 
Entry 
ENTRY 
ENTRY 
ENTRY 
Ll sENTRY 
ENTRY 
ENTRY 
ENTRY 
ENTRY 
ENTRY 
EnTRY 
ENTRY 
EnTRY 
ENTRY 
K CsEect 


DICTIONARY? 
PHASEs ADDRESS 


Root 
RooT 
Root 
ROOT 
Root 
Root 
Root 
root 
Root 
ROOT 
Root 
Root 
Root 
ROoT 
Root 
Root 
Root 
RooT 
Root 
ROOT 
ROoT 
ROoT 
Root 
RooT 
Root 


Oo00is8ES 
000016E0 
OoOOL SFC 
00001908 
0000190C 
ooo0isr4 
00001900 
Oocoleac 
00001916 
00001aS8 
000017Ca 
00000028 
0o0018FO 
Oooo sF4 
000018eCc 
00001888 
00001914 
Ooo0190Cc 
000018E8 
00001910 
00001904 
090018600 
00001904 
00001914 
00001888 


@e ALLOCATION MAP eo 


Size = 


TYPE 


OOO01F 6A 
€sio LNK ORG 
00000000 


00000000 
oooconis 
oococo20 
00000028 


60001530 
00001S0E 
o0ca!764 
Q0001796 
oo000!17C¢cs 


00001886 
oo00l a4 
0000188c 
0000158990 
000018FO 
ooooler4s 
ooo0lsre 
oocolarc 
00001900 
00001904 
00001908 
o0o000190¢ 
vooolszio 
ocool914 
ooo0l9ie 
o000191¢c 
00001920 
00001924 
gooole2a 
o000isESs 
oooolsE4 


SYMBOLe 


BUILD 
DELETE 
DUKCP 
€SumT 
GET 
GTAOR 
KESALP 
OMA 
P?CDA 
P?1MSO00 
P?SERIAL 
PuY 
Rotoc 
ROKEY 
ROKEYL 
Rose 
Rosel 
RDSR 
ROSRL 
RETURN 
SETLOAD 
SSUNLK 
Sus 
WRID 


HIADDR 
OOUGIFS69 


00001883 


00u01977 


Figure 9-7. Link Map for RCCUST (Part 1 of 2) 


PHASEs 


ROOT 
RontT 
ROoT 
ROnT 
ROoT 
ROoT 
ABS 

ROOT 
ROOT 
ROoT 
ROOT 
ROoT 
ROOT 
ROnT 
Root 
ROOT 
ROOT 
ROOT 
ROoT 
Roat 
ROOT 
ROOT 
ROOT 
ROnT 


LENGTH 
GOCOIF ba 


OEFERREN 


©e0000153nee 


00000354 


Socc00FN 





9-26 


VER800403 


ADDRESSe 


Uoootssec 
Qu0018FC 
00001880 
00001908 
GoooleFO 
00001900 
OoOOIFOA 
vo000020 
00001796 
00001530 
0u001976 
Quoolsers 
00001924 
OouolsB4 
0u001868 
ugoolseca 
O00018cC 
000018aCcO 
Gu0018C4 
00001928 
0000189C 
00001604 
000016a0 
OyOOI8FSa 


OBY ORG 


buco0000 
09000018 
gooc0020 
Gooonn28 
oyoo0000 


o0vo00g00 
QUGOOOAE 
00000234 
Qo0000266 
Ou000298 


00900000 
Goocoo0c 
vooo0004s 
Quoogn0s 
ovuoon0es 
voooa0gsc 
Qo000070 
Qvoo0dg74¢ 
Ogoc0078 
Qoocou7c 
Go000060 
Gooocus4 
o0uco008s8 
Oucoo0sc 
Oooc0090 
00000094 
ucoo009s8 
oago009Cc 
oooocgad 
Qo000060 
Qooooosc 














UP-9206 


PHASE NAME TRANS ADDR FLAG LABEL 

sus 
ROS@L 
RDIOC 
ROLOCL 
ROSQC 
ROSQ@CL 
ROSRC 
ROSRCL 
ROSGIC 
ROKEYC 
ROKEYCL 
ROKYIC 
GTADR 
DLADR 
ADOKY 
DELKY 
UNKCP 
DLKCP 
WRID 
RDIOD 
ROTOL 
ROKEY 
ROKEYVL 
ROKYI 
ROSR 
RDSRL 
ROS 
ROSeI 
STumT 
ESuMtT 
SSLOCK 
SSUNLK 
STCRE 
ENOCRL 
CcMORB 
OPENF 
SUBPROG 
SETLOAD 
GETLOAO 

= 79/08/08 1803 - P?SERIAL 
P?SERIAL 

= 79/08/08 17658 « P?SPLO00 
P?SPLO00 

+ 80/03/21 16650 « PIIMSIXO 
P?IMSIXO 

oo000000 


B= BLK DATA CSECT 
L = DEFERRED LENGTH 


~ AUTO@DELETED 
- MULTIPLY DEFINED 
S + SHAREO ITEM © UNDEFINED REF 
T 


*ANy OTHER CODES REPRESENT PROCESS ERRORS? 


LINK EDIT OF *RCCUST? COMPLETED 
OATE= 81/04/07 TIME© 10,37 
ERRORS ENCOUNTERED= C000 wUPSI= X*40° 


SPERRY UNIVAC OS/3 


FLAG CODES - 
E © EXCLUSIVE *A* REF 
WN © NOT INCLUDED 
v= vCON ITEN 


IMS ACTION PROGRAMMING IN RPG II 


eo SESE 


LINK MAP 


LNK ORG HIADOR 
000018A0 
ooo0lsoc 
oooolre24 
00001920 
oooolsic 
oooolgl4 
oooolelo 
oo00!sEs 
oooolse4s 
00001890 
oo00188c 
oooolssa 
00001900 
oooolerc 
OCcoolsa4 
ooo018asa 
oooolsac 
00001880 
oooclars 
oooorsero 
Qooolser4 
oo0018B4 
00001868 
oocol sec 
ooootsco 
oooolsc4 
oooolsacs 
oooolscc 
oo00l904 
000019086 
oocoisapa 
00001804 
00001808 
0000160C 
O000!18EO 
oo0019i6 
000016Aa0 
o000189¢ 
00001894 


00001978 00001 9DF 
o000!9E0 OOOOLAS7 


oo00sa58 Oooo!lFrse9 


G = GENERATED EXTRN 
P = PROMOTED COMMON 


Figure 9-7. Link Map for RCCUST (Part 2 of 2) 
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LENGTH OBY ORG 
Oocco0018 
Qoooc0s4 
Ooooou9c 
00000096 
ooocons4 
Ovucooose 
Goooocse 
Oogo00060 
Ouagooosc 
Go000008 
Ooo00004% 
Oooco000 
Ovuocoo7s 
Ougoou74 
Gooacoic 
Ooa00u20 
Quooou24 
ogo00028 
voooou70 
ugo0006s8 
Qoaon0ec 
oooooazc 
00000030 
00000034 
Oguoon3e 
0000003C 
Qo000040 
vo000044 
Quooaa7c 
00000080 
Oooco04sS 
oooo0004c 
oooo00so 
00000054 
Qoooo0ss 
00000090 
00000018 
Ogo000014 
00000010 


0000006a 00000000 
00000078 0o000000 


oooo0st2 Quo00000 


I - INCLUSIVE *V* REF 
R © SHARED REC PRODUCED 
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SYMBOL TABLE 





; NOTE 132 
SymBO. TABLES 


RESULTING INDICATORS 

ADDRESS RI ADDRESS ADDRESS ADDRESS ADDRESS ADORESS ADDRESS 
Gooor4 ip ooools oo0nls 000017 000018 O0002A 000034 
O0003F 41 000040 oco048 000053 9oo00sc¢ OQ007A o0n08s 
000086 H1 000087 oo0css a00089 OoaosA ooo0ss oonusc 
Go008D He OO008E oo00eF 000090 000091 900092 000093 
Q00094 Us 000095 000096 


FIELD NAMES 


AODRESS FIELD ADDRESS FIELD ADORESS FIELD ADORESS FIELD ADORESS FIELO 


000180 eERROR 000210 Cust 000215 SIGN 000216 AMOUNT 000218 CusTIO 
000220 NAME 000234 ADOR 0002%3 CiTy 000252 ZIP 000257 BALDUE 
00020C END Q0025c AMT OQOO2SF NEWBAL 


LITERALS 
ADORESS LITERAL ADDRESS LITERAL ADDRESS LITERAL 


000265 + 000266 - 000267 x*n0003°* 
900269 x*100A0200° 000260 NAME - 000277 x*10010300" 
000278 ADDRESS - 000285 x*100!10400* 000289 City-ST - 
000293 xK*1I00I104IE°* 000297 ZIP - 000290 x*10040200° 
O002Al OLD BALANCE - o0024F o,ern ees .or Ooo2B8F x*10040100" 
0002C3 TRANSACTION - 000201 e/eccwe O0Q2DA NEw BALANCE = 
oo002c8 geregeoayor/ene o 

o10 CcusTio NOTE 205 

000 NOTE 115 


LITERALS 
ADDRESS LITERAL ADDRESS LITERAL ADDRESS LITERAL 


000368 x*10010106° 00038C RCMENU 000392 OD 
000393 INVALIO CUSTOMER ID QOO3A6 INVALIO SIGN 000382 INVALID AMOUNT 





NOTE 115 THE NUMBER OF SYMBOLS USED IN THIS PROGRAM CAUSED THE COMPILER TO RUN LESS 
EFFICIENTLY THAN IF AN INCREASED MEMORY SIZE WERE ALLOCATED. 


NOTE 132 NO INPUT AND/OR CUTPUT SPECIFICATIONS FOUND FOR THIS FILEe 


NOTE 205 WARNING? FIELD NAME IS UNREFERENCED. 





Figure 9-8. Symbol Table for RCCUST 
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MESSAGE FORMATTING 


Appendix A. Using Device Independent 


Control Expressions and 
Field Control Characters 


You use device independent control expressions (DICE) to format 
input and output messages handled by action programs. These 
codes control various operations, such as cursor positioning and 
carriage return, on the terminal screen. 


This appendix supplies all DICE sequences’ and _ their 
interpretations, and describes how to use them in formatting 
messages. In addition, it presents limited information concerning 
the use of field control characters. 


A.2. FORMATTING MESSSAGES 


Other ways to format 
messages 





There are numerous methods for formatting output messages. 
The action program can use: 


P Screen format services. For a complete discussion of how to 
use screen format services, see Section 6. 


> Device independent control expressions 


> Format control expressions with UNISCOPE 100 and 200 
display terminals 


> Field control characters (FCCs) with workstations and 
Universal Terminal System terminals 


UP-9206 


MESSAGE FORMATTING 


DICE and FCCs 


Format control expressions 


Use of format control 
expressions 


Handling DICE sequences 


Functions performed 
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This appendix supplies information on DICE sequences and how 
to use them. We will also include limited information concerning 
field control characters since one program, RCMENU, presented 
in Section 3 of this manual uses this type of formatting. For 
detailed information concerning format control expressions, 
consult the UNISCOPE display terminal programmer reference, 
UP-7807 (current version). 


When a program uses format control expressions, it must include 


a different formatting routine for each type of terminal receiving 
the output. Figure A-1 illustrates this. 


OUTPUT TEXT AND CONTROL CHARACTERS 






eBoy 





REMOTE 
DEVICE 
HANDLERS 


USER 
PROGRAM 





LEGEND: 


Zew 


eee, ee” 
Terminal-Oriented 
Control Characters 





Figure A-1. Using Terminal-Oriented Control Characters to Format Messages 


Using DICE sequences to format messages eliminates this 
problem. The remote device handler converts DICE sequences to 
control characters for each destination terminal, regardless of 
type. Some of the control character functions are: 











| cursor movement to the first space of a new 
line 

a ~ cursor to the home position of a new page 

a ~ cursor to the beginning of the same line 

a , to a specific row and column on a 





disp ay 
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MESSAGE FORMATTING 


DICE placement You can place DICE sequences anywhere in a message. As you 
can see in Figure A-2, DICE sequences simplify message 
formatting. 


OUTPUT TEXT AND DICE 


Ujrex Yrexr y) 


ZA ZA LZ 





REMOTE 


USER 


PROGRAM PEVICE 


Coding with DICE 





LEGEND: 


: mM Bes DICE Characters 
a 


Terminal-Oriented 
Control Characters 


Figure A-2. Using Dice Sequences to Format Messages 





Using input DICE For input, control characters received in a message are converted 
into DICE sequences by the remote device handler. For certain 
terminals, your program can analyze these sequences to 
determine cursor position. In addition, input DICE is handy for 
message switch applications because control characters in each 
input message are converted to DICE sequences. The remote 
device handler converts these sequences into the appropriate 
control characters for the destination terminal. 


Stripping DICE When you specify EDIT=c or EDIT=tablename in the ACTION 
section of the IMS configuration, input DICE is stripped from your 
input message. You should specify EDIT=c or EDIT=tablename 
in your IMS configuration. (Specify EDIT=tablename only when 
you generate an edit table for the action. See Appendix B.) 


UP-9206 


MESSAGE FORMATTING 
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A.3. DICE AND ICAM 


Defining DICE at network 
definition 


DICE=(ON) is 
recommended 


You can turn DICE on or off when you _ define your 
communications network with the DICE operand of the TERM 
macroinstruction. 


saga ( ON ) 
OFF 


where: 
DICE=(ON) 
The remote device handler creates input DICE according 
to your input terminal cursor movements: DICEs are 
created automatically. 
DICE=(OFF) 


The remote device handler doesn't create input DICE. 


The default is DICE=(ON). We recommend that you specify 
DICE=(ON) or omit this operand because many IMS features 
require the use of input DICE. Certain terminal commands and 
IMS transaction codes aren't available when you _ specify 
DICE =(OFF). 


See ICAM concepts and faciltiies, UP-8194 (current version), for 
a detailed explanation of input DICE creation, and the IMS system 
support functions user guide, UP-8364 (current version), for 
specific IMS considerations. 
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DICE SEQUENCES 


A.4. THE FORMAT OF DICE SEQUENCES 


DICE format The format of a DICE sequence is: 


select function ee 
character code 


where: 





select character 
Is a hexadecimal character (10) designating the start of 
a DICE sequence. 


function code 
Defines the device control sequence that is recognized 
by the remote device handlers on input. On output, this 
code is a 1-character field defining the operation to be 
performed on the text message. DICE function codes are 
listed in Table A-1. 


m field and n field 
These fields are treated as parameters to the DICE 
function code. Their actual definition varies and is 
determined by the _ individual DICE macroinstruction. 
Generally, m relates to vertical positioning and n refers 
to horizontal positioning. 


Text message alignment These fields may be expressed in absolute values (m, 
and n,) or relative displacement values (m, and n,). The 
absolute values align the text message to the actual 
location (row and column) on a page or screen. The 
relative displacement values give a relative location from 

Cursor movement the present position of the cursor, that is, move cursor 
two rows down and one column to the right. All values 
are expressed in hexadecimal notation. 
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DICE INTERPRETATION 

DICE commands Table A-1 illustrates all the possible DICE input/output 


commands and their explanation. 


ZO#BEG 
ZORTABS 


ZO#FORMA 
ZO#ERSLN 


Table A-1. DICE Input/Output Commands, Codes, and Device 
Interpretation (Part 1 of 4) 


Beginning 
of current 
line control 


Set tab stop 
at an 
absolute 
position 4 


Forms control 
with clear; 
protected/ 
unprotected 
data 


Erase to 
end of line 


New line control 


SCw4oco;, HOVZ- |] HOCwHCO |, HCW Zz 


ASC PVHNOCO |, HOV SZ 





ACVNC Oo) ACV]Z— 


ACPA CO yy Hoe Z— 


Carriage return 


Carriage return 
followed by m 

line feeds and 

spaces to the 
night 


Carriage return, 


Carriage return, 
line feed, fol- 
lowed by m line 
feeds and n 
spaces to the 
right. 


Move cursor to 
beginning of current 
line. Then move 
cursor m lines down 
and n columns to 
the right. 


Set tab stop at row 
m and column n. 


Not used 


Move cursor to row |Action is optional.2) 


m and column n 
and clear pro- 
tected/unprotected 
data to end of 
screen. 


Not used 


Cursor does not 
move. Unprotected 
data to the end of a 
line or to the end 
of the first unpro- 
tected field is 
cleared, whichever 
comes first. 


Cursor return 


Move cursor to 
beginning of next 
line. Then move 
Cursor m lines 
down and n col- 
umns to the right 


Advance m lines. 


Not used 


dvance m lines. 








Advance 0 lines. 





m line feeds and n 
spaces to the right. 


Not used 


Action is optional. @ 


Not used 


Line feed, followed 
by m line feeds and 
n spaces to the 
right. 
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DICE INTERPRETATION 





ZO#POSC 


ZOHCUR 





ZO#CURC 





ZQHCOORD 


ZO#FORM 


New line control 
with clear 


Current position 06,5 
control 


Current position 0716 
control 
with clear 





Set coordinates 


Forms control 02, 















Carriage return, 
line feed, fol- |cept area between 
owed by m line} start and end posi- 
feeds and n tions is cleared. 
spaces to the 
right 


Same as 04;,¢ ex- 






ASC WASCO ~noOwse— 


ot used 


Advance (m+1) 
lines. 





Line feed 








Move cursor m lines 
land n spaces to} down and n columns| 
the right to the right 


Not used 
m line feeds Insert n spaces if 
: ; 





ASOwPAHCO;AcCwvZz— 









and n spaces tof nonsignificant space 
the right suppression is 
allowed. If not, insert 
n DC3 characters; m 


is not interpreted. © 








acwrHCO ,aScrse- 


m and n represent 
the start-of-entry 
(SOE) cursor 
coordinates. 


Move cursor to row 
m and column n. 








“Cc Uz 


Move cursor to row 


aces cCoO 





n—1 spaces to 
the right) 















Advance m lines. 





Advance m lines. 















Not used 


End of input card | Not used 


Table A~1. DICE Input/Output Commands, Codes, and Device 
Interpretation (Part 2 of 4) 


Not used 


Line feed, followed 
by m line feeds and 
n spaces to the right 





Insert n spaces it 
nonsignificant space 
suppression is allowed. 
If not, insert n DC3 
characters; m_ is not 
interpreted. 








Insert n spaces if 
Nonsignificant space 
suppression ts allowed. 
If not, insert n OC3 
characters, m ts not 
interpreted. 








Not used 


Action is optional. Action is optional, @ 


Not used 


op of form and 


Not used 


Form feed, line feed, 


advance to line m | and advance to 
(m-1 line feeds) 


tine m and column 

n (m—1 line feeds 
and n—1 spaces to the 
right) 
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DICE INTERPRETATION 


Table A-1. DICE Input/Output Commands, Codes, and Device 
Interpretation (Part 3 of 4) , 



















ss = 
ZO#FORMC =| Forms contro! | Not used Not used Not used Not used 
with clear N 
unprotected P 
data U 
f 
0 Action is Move cursor to row jAction is optional@ Action is optional. @ 
U optional. m and column n, 
iF and clear unpro- 
P tected data to 
U end of screen. 
T 
NOTES: 


@ Most character-oriented terminals can be strapped to handle the carriage return (CR) 
character and the line feed (LF) character as follows: 


s CR 
1. print mechanism moves to beginning of the same line; or 


2. print mechanism moves to the beginning of the same line followed by a 


line feed. 
a LF 
1. line feed (no column change); or 
2. line feed followed by return of the print mechanism to the beginning of 


the new line. 


To achieve device independence between terminal types, the character-oriented 
terminals must use the first option for CR and the first option for LF if the device 
macroinstruction is ZO#CUR or ZO#BEG. 


Use the first option when the character-oriented terminals are a part of a message 
switch environment. 


Certain terminals do not have a form feed capability (i.e., some teletypewriters). For 
these terminals, the DICE expressions that specify form feed will line feed. 


@ The set coordinates macroinstruction (ZO#COORD) or the forms control with clear 
macroinstruction (ZO#FORMC), when acted upon by character-oriented or 
page-printing terminals, will vary in its action, depending on the usage of the DICE 
keyword parameter of the TERM macroinstruction at network definition time: 


TERM ...,DICE? FORMS ee... 


When FORMS is specified, the set coordinates macroinstruction is interpreted as the 
forms control macroinstruction. 


When NEWLINE is specified, the set coordinates macroinstruction and the forms 
control with clear macroinstruction result in a carriage return, line feed for 
character-oriented terminals, or advance one line for page-oriented terminals; m and 
n are not interpreted. 


When the DICE parameter is not specified, the default option is NEWLINE. 
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DICE INTERPRETATION 


Table A-1. DICE Input/Output Commands, Codes, and Device 
Interpretation (Part 4 of 4) 


@ The UNISCOPE display terminal suppresses nonsignificant spaces on each line 
(except for the line containing the cursor) when text is transmitted to the processor 
or printed locally on the COP or TP. 


Your program may send data to the UNISCOPE screen containing significant blank 
segments that include the last column of the screen. If this data is transmitted from 
the terminal to the processor or is printed locally on the COP or TP, the blank 
segments must consist of nonspace characters that are nondisplayable. The DC3 
character meets these qualifications. The ICAM interface provides your program 
with the capability to prevent nonsignificant space suppression on the UNISCOPE 
display terminal. The ‘‘current position control with clear’ is the only DICE 
macroinstruction that can perform a clear function if your program is preventing 
nonsignificant space suppression. 


NOTE: 


The ASCIl-to-EBCDIC translation table is modified so that the DC3 character is 
translated to space 40,, for input from the UNISCOPE display terminal. 


@ Using DICE function code 09,, for setting a tab stop, m=O and n=O results in a 
tab stop being placed at the current cursor location (no cursor positioning is 
performed). This applies to UNISCOPE and UTS devices only. For teletypewriters 
and DCT 500 terminals, a space character is inserted. 


When m or n is greater than the maximum allowable m or n, action varies 
depending on the remote terminal: 


= UNISCOPE display terminals - wraparound occurs on the screen. 


a Character-oriented terminals - gives different results depending on device 
characteristics. 


A.5. INTERPRETING DICE SEQUENCES 


Device independent When using DICE, your program doesn’t need to be aware of the 
terminal type. A particular DICE denotes the same positioning on 
any terminal. There are some exceptions that result from terminal 


limitations. 
Factors controlling The interpretation of a DICE by the remote device handler is 
interpretation of controlled by: 


DICE sequences 


> DICE function code 
DICE m and n fields 


b 
> The terminal involved 
> 


The particular device on the terminal being used 
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DICE INTERPRETATION 





Terminals supporting DICE The remote device handlers currently provide device-independent 
support for three classes of remote terminal devices: 


Hard copy, 1. Hard copy character-oriented devices, such as the SPERRY 

character-oriented devices UNIVAC Data Communications Terminal 475 (DCT 475), 
Data Communications Terminal 500 (DCT 500), Data 
Communications Terminal 524 (DCT 524), and Data 
Communications Terminal 1000 (DCT 1000), and TELETYPE 
teletypewriter models 28, 32, 33, 35, 37. 


Hard copy, page 2. Hard copy page printer type device, such as the SPERRY 

printer devices UNIVAC 1004 Card Processor System, Data 
Communications Terminal 2000 (DCT 2000), and 
9200/9300 Systems, and the IBM 2780. 


CRT terminals 3. CRT-type terminals, such as the UNISCOPE 100 and 200 
and the UTS 400 Display Terminals. 


Table A-2 defines the primary output device and the primary 
input device for each terminal type. 


Table A-2. DICE Primary Devices 





DICE primary devices 













Character-oriented terminals Printer 


Printer 
Screen 


Keyboard 


Page printing terminals Card reader 








CRT terminals Keyboard 


Auxiliary devices supported |n addition to the specified primary devices, each terminal has the 
ability to support one or more auxiliary devices. The auxiliary 
devices suggested by each terminal are listed in Table A-3. 








& 
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DICE INTERPRETATION 


Table A-3. DICE Usage for Auxiliary Devices 









UNISCOPE 















Stet th 


DICE is applied to the 
cop. @) 


2 Tape cassette (TCS) 

a Communications output 
printer (COP) 

800 terminal printer (TP) 









DCT 1000 





Card reader/card punch 
Paper tape reader/punch 


a Paper tape reader/punch 


s Tape cassette (TCS) in paper 
tape read and write only 


DICE is applied as if the 
output/input is to/from 
the primary device, even 
though it is for the 
auxiliary 


device. @ 





DCT 500/TTY 


DCT 524 









Batch terminals DICE is used for 
end of network buffer 
sentinel. 

No forms control action 


is taken. 


NOTES: 


@ When the print transparent option is not used, DICE is applied to the UNISCOPE 
screen even though the output is sent to an auxiliary device of the UNISCOPE 
terminal. In this case, the format of the data printed on the COP or TP is identical to 
the screen format. Nonsignificant space suppression by the UNISCOPE terminal may 
have to be prevented to keep the formats identical. 


The full capability of DICE cannot be applied to the COP because of hardware 
characteristics. All data to a UNISCOPE auxiliary device passes through the 
UNISCOPE terminal. When DICE is applied to the COP, the use of print transparent 
mode means that no carriage returns are transferred to the COP. Line feeds and 
form feeds take a storage position in the UNISCOPE storage and are nondisplayable. 
These characters are passed to the COP where: 


a an LF causes a line feed followed by return of the print mechanism to the 
beginning of the new line; and 


a an FF causes a page eject and positioning of the print mechanism at the 
beginning of the first line of the form. 


The COP has no tabbing capability. 


These characteristics are reflected in the interpretation of DICE output function 
codes for the COP as shown in Table A-2. 


For messages sent to a UNISCOPE auxiliary device with transparent transfer, the 
cursor to home (ESC e) sequence is inserted at the beginning of the text by the 
RDH. 


@ The control characters that are generated from the DICE macroinstructions are 
always created for the primary device of a character-oriented device, even though 
your program is sending to an auxiliary device. The message and these control 
characters (carriage returns, line feeds, form feeds, and spaces) will be 
punched/written by the output auxiliary device that was specified by your program 
or was switch-selected by the terminal operator. If the punched/written data is later 
read by the terminal's input auxiliary device, the carriage returns, line feeds, and 
form feeds are converted to input DICE as specified in Table A-1. 
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A.6. USING DICE IN AN RPG Ii ACTION PROGRAM 


Coding DICE sequences To format an output message, you enter DICE sequences on the 
output form in columns 45-70, along with the message text. The 
remote device handler takes the DICE sequence and converts it 
into the form required by the destination terminal. The 
4-character DICE sequence determines how the output message 
looks when it appears at the terminal. The DICE sequences 
themselves never appear on the terminal screen. 


Example Figure A-3 shows how an action program generates a formatted 
output message using DICE sequences. Figure A-4 shows how 
the message looks when it appears at the terminal. 





STACKER SELECT! 
FAFETCH OVERFLOW 


TYPE M/D/TIE 














CONSTANT OF EDT WORD 





Fag a Wa Ei Wa a aa ne a Ur 





X NOOABCA| 6,” 
tt AP) E. 
MEL NOON OC2! 
67| {* THE, TPT, 
TUL NOBHO1226 0.00) 
Eo! ‘TO, FORMAT. Your’) ....., 
GO KN OOBG2265. . .. 01. iy 

7 






































¢ 





























Figure A-3. Using DICE to Format an Output Message 


COLUMN 30 32 34 38 





Figure A-4. How DICE Formatted Message in Figure A-3 Appears at the Screen 
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CODING DICE SEQUENCES 





Here is a brief description of the DICE sequences used in Figure 
A-3. 


Description of DICE 
sequences (Fig. A-—3) 





1OO0AOA1E | The select character 10 signals the start of the DICE sequence. 


The function code (OA) clears all protected and unprotected data from 
the terminal screen. 


The m field (OA) and the n field (1E) position the cursor to row 10, 
column 30. Notice that the end position for the DICE sequence is 20. 
Remember that the DICE sequence is a 4-character code and that the 
output message area header occupies positions 1-16. 


10010C20 The select character 10 is always the same and signals the start of the 
DICE sequence. The function code (01) sets coordinates as directed by 
the m and n fields of the DICE sequence. 


The m field (OC) and the n field (20) position the cursor at row 12, 
column 32. 


10040122 The select character is the same as before. The function code (04) 
moves the cursor to the beginning of the next line and then sets the 
coordinates as directed by the m and n fields. 


The m field (01) and the n field (22) position the cursor one row below 
where it presently is and in column 34. 


10080226 The select character is again the same. The function code (08) returns 
the cursor to the beginning of the current line. The m field (02) and the 
n field (26) position the cursor two lines below the current fine and in 
column 38. 
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A.7. USING FIELD CONTROL CHARACTERS 
The FCC sequence format is: 


Field control character format FCC SEQUENCE 





Characters in the FCC sequence are defined as follows: 





Defining FCC characters 
Is the control character that signals the start of an FCC 
sequence. It corresponds to a hexadecimal 1F. 





Is the number of the row in which the FCC is placed. 





Is the number of the column in which the FCC is placed. 





Is the hexadecimal value placed in the sequence to 
define bits 4, 5, 6, and 7 of the FCC. Table A-4 lists 
the hexadecimal codes you can use. 





Is the hexadecimal value placed in the sequence to 
define bits O, 1, 2, and 3 of the FCC. Table A-5 lists 
the hexadecimal codes you can use. 


Table A-4. Hexadecimal Codes Used as M in the FCC Sequence (Part 1 of 2) 













Tab stop, normal intensity, changed field* 


Tab stop, display off (no intensity), changed field* 


2 Tab stop, low intensity, changed field* 

3 Tab stop, blinking display, changed field* 
4 Tab stop, normal intensity 

5 Tab stop, display off (no intensity) 

6 Tab stop, low intensity 

7 Tab stop, blinking display 


Not tab stop, normal intensity, changed field* 
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Table A—-4. Hexadecimal Codes Used as M in the FCC Sequence (Part 2 of 2) 





Not tab stop, display off (no intensity), changed field* 











Not tab stop, low intensity, changed field* 


Not tab stop, blinking display, changed field* 


< Not tab stop, normal intensity 
= Not tab stop, display off (no intensity) 
> Not tab stop, low intensity 


Not tab stop, blinking display 





* Normally, when an FCC is generated by the host processor, the changed-field designator 
is cleared. However, the host processor can generate individual FCCs with the 
changed-field designator set; this capability may be used for selective transfer or 
transmission of fields which were not in fact changed by the terminal operator. By 
sending an ESC u code to the terminal in a text message, the host processor can clear 
the changed-field designators in all FCCs without regenerating each FCC and without 
altering the data within the fields. 


Table A-5. Hexadecimal Codes Used as N in the FCC Sequence 





Any input allowed 











Alpha only allowed 


2 Numeric only allowed 

3 Protected (no entries and no changes allowed) 
4 Any input allowed, right-justified 

5 Alpha only allowed, right-justified 





Numeric only allowed, right-justified 


For detailed information on using field control characters, 
consult the UTS 400 programmer reference, UP-8359 (current 
version). 
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EDIT TABLE GENERATOR CODING RULES 


Appendix B. Generating Edit Tables 


B.1. PURPOSE 


The edit table generator offers a convenient means for 
converting unformatted input received from terminal operators 
into fixed formats required by action programs and checking this 
input for types of data, value ranges, and presence of required 
fields. 


Edit table generator output The output of the edit table generator is written to the named 
record file (NAMEREC). From there it is loaded at the 
& appropriate time by IMS. Each edit table is associated with a 
particular action at configuration time via the EDIT parameter in 
an ACTION section. The edit table utility can be run either 
before or after configuration, but the NAMEREC file must be 
previously initialized. 


B.2. STATEMENT CONVENTIONS AND CODING RULES FOR EDIT TABLE 
GENERATOR INPUT 


Edit table generator input Input to the edit table generator is in the form of keyword 
parameters parameters that define the edit table, the fields you want edited, 
and the edit criteria for each field. 


Statement conventions In the format for edit table parameters, these conventions are 
observed: 






Capital letters represent entries that must be coded exactly 
as shown. 







Lowercase words are generic terms representing data that 
you must supply. 







Entries within braces represent choices, of which you select 
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Data within brackets represents optional entries. 


Shaded entries are default values. 


To code input to the edit table generator, apply the following 
rules: 


Sequence numbers 1. Input entries must contain sequence numbers in columns 77 
through 80, in ascending order. The lowest permissible 
sequence number is 0001. 


Where to code parameters 2. Parameters can be coded in any column between 1 and 76. 
Blanks are ignored and are permitted anywhere in the edit 
table definition. 





Example: 
1 77 80 
a) eee 
SEP=;ETAB=ETABTST ;KEY=1;POS=@;MAN=Y;LEN=5; 9100 
KEY=2;FIL= ;JUS=L;LEN=15;MAN=Y;TYP=A;POS=5; 0200 
KEY=3;FIL= ;JUS=L;LEN=20;P0S=20;TYP=M;; 0300 
Spanning lines 3. Specifications for an edit table and for each field can span 


more than one line. However, a keyword and its value must 
be contained on one line. 


Example: 


INCORRECT CORRECT 


SEP=; ETAB=ETABTST ;KEY=1;POS= SEP=; ETAB=ETABTST ;KEY=1;POS=0; 0100 
®;MAN=Y;LEN=5;MAN=Y;LEN=5;; 


KEYWORD AND VALUE 
NOT ON SAME LINE 
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New line 4. A new edit table specification must start on a new line. Each 
field need not begin on a new line. 


Example: 


INCORRECT CORRECT 


SEP=;ETAB=ETABTST ;KEY=1;POS=0; 0100 SEP=;ETAB=ETABTST ;KEY=1;POS=0; 
MAN=Y;LEN=5; 0200 MAN=Y ;LEN=5;KEY=2;FIL= ;JUS=L; 
KEY=2;FIL= ;JUS=L;LEN=15;MAN=Y; 0300 LEN=15;MAN=Y; TYPSQ; 


TYP=A;POS=5;;SEP=,ETAB=TABL1,  @400 | SEP=,ETAB=TABL1,KEY 
KEY=1, LEN=20, POS=20 0500 | pos=20,, 


NEW EDIT TABLE NOT NEW FIELD NEED NOT 
SPECIFIED ON NEW LINE START ON NEW LINE 





Field separator character 5. The field separator character specified by the SEP keyword 
parameter must be used as the field separator throughout 
the edit table specification, as well as the input message to 
be edited. Double separator characters indicate the end of 

Changing separator character the edit definition. A new edit table can establish a different 
separator character. 


& Example: 


INCORRECT CORRECT 


SEP=;ETAB=ETABTST , KEY=1, POS=0; SEP=; ETAB=ETABTST ;KEY=1;POS=0; 
MAN=Y ; LEN=5; MAN=Y;LEN=5;; 

SEP=.ETAB=TABL4.KEY=1.POS=0. 
END OF EDIT SAME FIELD MAN=Y.LEN=3> 


DEFINITION SEPARATOR 


NEEDS DOUBLE NOT USED ESTABLISHES A NEW 
SEPARATOR THROUGHOUT SEPARATOR CHARACTER 
EDIT TABLE 
DEFINITION 
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Order of parameters 6. The SEP, ETAB, and KEY parameters must be coded in the 
prescribed order; the remaining keyword parameters can be 
specified in any order. SEP and ETAB are coded once for 
each edit table. The remaining parameters are repeated for 
each field in the input message to be edited. 


INCORRECT CORRECT 


SEP=;POS=0; LEN=5;KEY=1; SEP=; ETAB=ETABTST ;KEY=1;POS=0; 
ETAB=ETABTST; + MAN=Y;LEN=5;; 


ETAB AND KEY PARAMETERS 
DON'T IMMEDIATELY FOLLOW 
SEP 





Numeric values 7. Numeric values are positive unless preceded by a minus sign 
(-). The plus sign (+) is not permitted in numeric values. 


Example: 


INCORRECT CORRECT 


SEP=;ETAB=TABLI;KEY=1;LEN=5; 0100 SEP=;ETAB=TABL1;KEY=1;LEN=5; 
POS=0 ;MAX=+200000;MIN=-1;; 0200 POS=0;MAX=20000;MIN=-1;; 


PLUS SIGN 
NOT ALLOWED 


NUMBER OF CHARACTERS 
EXCEEDS LENGTH GIVEN 
IN LEN PARAMETER 
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B.3. EDIT TABLE GENERATOR PARAMETERS 


Input parameter format The input parameters you give to the edit table generator should 
follow this format: 


SEP=separator-character 
ETAB=tablename 
pase ecb } 

position 
LEN=field-length 
POS=starting-position 
[FIL=fill-character ] 


a) 
ot 


[MAX=max imum- value] 
[MIN=minimum- value] 
YP=/A 








Separator character The separator parameter specifies the field separator character 
for both the edit table definition and the input message to be 
edited. It cannot be a blank, equal sign, or minus sign. This 
parameter is required, must be the first entry on the first line of 
the edit table definition, and can be specified only once per edit 
table. 


(SEP) 





Edit table name The edit table name parameter names the edit table and must 

(ETAB) immediately follow the SEP parameter. This _ specification 
associates the edit table with an action at configuration, via the 
EDIT =tablename option in the ACTION section. 





UP-9206 


SPERRY UNIVAC OS/3 B-6 
IMS ACTION PROGRAMMING IN RPG II 


EDIT TABLE GENERATOR INPUT 


Key field identification 
(KEY) 


Positional fields 


Keyword fields 


Edited field length 
(LEN) 





The key field parameter identifies the input message field for 
which edit criteria are specified in subsequent parameters and 
must be the first parameter specified for each field. The edit 
table generator associates all subsequent specifications with this 
field until it encounters another KEY parameter. Input fields can 
be positional or keyword. Positional fields precede keyword 
fields. 


KEY=position specifies the relative position of the field as it 
appears in the input message. Positional fields must be defined in 
numeric order, starting with 1. 


KEY=keyword specifies a 1- to 3-character alphanumeric 
identification. The first character must be alphabetic for a 
keyword field in the input. The terminal operator enters keyword 
fields in the form keyword=data. For example, when you specify 
KEY=OLD, the terminal operator might enter OLD=57500 for 
this field. Once a keyword field is identified in the edit table 
definition, all subsequent fields must be defined as keyword 
fields. 


Figure B-1 shows the correct coding for positional and keyword 
parameters to the edit table generator. 


-IKEY=2);FIL= ; JUS=L;LEN=15 ;MAN=Y ;TYP=A;POS=5; 
Vaaetbne ; JUS=L ;LEN=10;POS=20;TYP=M; 





Figure B-1. Edit Table Parameter Description with Positional and Keyword 
Parameters 





The length parameter specifies the length of the edited field and 
is a required parameter. You may specify a maximum of 255 
characters for alphanumeric fields and four characters for binary 
fields. Ten characters is the maximum length for numeric fields 
unless you specify both MIN and MAX parameters for this field. 
If you identify a numeric field in the action program as packed 
decimal, you can specify up to 16 characters in the LEN 
parameter. 
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Field-length longer than 
screen width 


Binary and packed field 
lengths 


Transaction codes under 
five characters 


Transaction code field 
larger than five characters 


Field starting position 
(POS) 
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NOTES: 


7. If the field-length is larger than the width of the screen on 
which data is to be entered, IMS removes the DICE code at 
the end of each line of terminal input and replaces it with a 
blank character. You must provide for these additional blank 
characters in the action program and include them in the 
field-length specified by the LEN parameter. 


2. The length specified for binary (TYP=B) and packed 
(TYP=P) fields is the maximum length for the field in the 
input message, not the length of the field in your program. 
For example, if a field is defined as packed with a LEN=3, 
the largest number the terminal operator can key in is 999, 
even though 1000 may be represented in a packed field in 3 
bytes. 


3. If the transaction code (the first | TRANSACTION CODE IS PAY 
SO OPERATOR ENTERS 


field in the input message) is less 
than five characters, the terminal 
operator must key in a_ space 
before entering the separator 
character for the next field. You 
must include the space in the 
field-length specified by the LEN 
parameter. 





The length of the first field can be greater than five 
characters, but only the first five characters are used in the 
transaction code. The LEN parameter should specify the 
actual length of the field. 





The starting position parameter specifies the starting position of 
this field as it appears in the edited message and is a required 
parameter. The first field starts at O. 
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Fill character 
identification (FIL) 


Field justification 
(JUS) 


Mandatory field 
(MAN) 


Maximum value limitation 
(MAX) 


Minimum value limitation 
(MIN) 








The fill character parameter optionally specifies the fill character 
inserted in the edited field when the data the terminal operator 
enters as input is shorter than the field-length specified by the 
LEN parameter. The default fill character is O. If you want to fill 
with spaces (X‘40’), code either FIL= or FIL=A; i.e., you can 
include or omit a space before the separator character for the 
next field. Binary fields are always filled with binary zeros; 
therefore, this parameter is ignored if specified for a binary field. 





JUS=L left-justifies this field in the edited message. Binary and 
packed fields are always right-justified; therefore, this parameter 
is ignored if specified for binary or packed fields. 


JUS=R right-justifies this field in the edited message and is the 
default assumed. 





MAN=N indicates that this field is not mandatory in the edited 
message for input to be acceptable. 


MAN=Y indicates that this field is mandatory in the edited 
message. 





The maximum value parameter specifies the maximum value 
allowed for the field in the input message. This parameter applies 
only to numeric fields. The highest value allowed is 2 to the 
thirty-first power minus 1 (231-1). The number of characters in 
this value must not exceed the length specified by the LEN 
parameter. 


The minimum value parameter specifies the minimum value 
allowed for the field in the input message. This parameter applies 
only to numeric fields. The lowest value allowed is minus 2 to 
the thirty-first power minus 1 (-(231-1)). The number of characters 
in this value must not exceed the length specified by the LEN 
parameter. 
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Data type (TYP) 


EDIT TABLE GENERATOR INPUT 





The type parameter describes the type of data to be contained in 
the edited field. 


TYP=A specifies alphabetic data. A field defined to the editor as 
alphabetic is treated as an alphanumeric field. 


TYP=B specifies binary data. 
TYP=M specifies alphanumeric data and is the default value. 
TYP=N specifies numeric data. 


TYP=P specifies packed decimal data. 
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B.4. EXECUTING THE EDIT TABLE GENERATOR 


Job control stream 


When execution is 
successful 


Duplicate edit table name 


Errors in edit table 
generation 


Once you code input parameters describing the edit table format 
and the NAMEREC file is initialized, you can execute the ZH#EDT 
edit table generator using the control stream illustrated in Figure 
B-2. 


/ JOB ADDEDT,, 

/ DVC 20 // LFD PRNTR 

/ OPTION DUMP 

/ DVC 5@ // VOL 089999 // LBL NAMEREC,DS9999 // LFD NAMERE 
(7/7 EXEC ZHHEDT 

/$ 


input parameters 





Figure B-2. Sample Execution of Edit Table Generator 


If the input definition is acceptable, the generated edit table is 
written to the NAMEREC file and the following message is 
issued; 


tablename ADDED 


If the edit table has the same name as a table already existing in 
the NAMEREC file, the new edit table replaces the existing table, 
and the following message is issued: 


TABLE ADDED, DUPLICATE DELETED 


If errors cause rejection of the edit table, the following message 
is issued: 


tablename REJECTED 
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UPSI byte values Another way to determine edit table errors is to look at the UPSI 
byte. The following UPSI byte values pertain to the edit table 


error Status: 







No errors 





Warning. ZH#EDT continues processing edit table input 
parameters but no edit table is built. 






Fatal error. Edit table processing terminates. 
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B.5. ERROR PROCESSING 


Warning errors 


Fatal errors 


Error message format 


When the edit table generator encounters a file 1/O error or 
certain types of input errors, it terminates and prints a message 
in the output listing. The resulting value in the UPSI byte is 80. 
Most types of input errors do not cause termination. Processing 
and validation continues, but an error message is printed and the 
edit table is rejected. Input specifications for the edit table 
generator are not printed in the output listing. This type of error 
results in an UPSI byte value of 40. 


If an |I/O error occurs while reading input to the edit table 
generator, the following message is issued, and the program 
terminates with an UPSI byte value of 80: 


INPUT READ ERROR, SCAN TERMINATED 


If an error occurs while opening, reading, or closing the named 
record file, the following error message is issued and the 
program terminates with an UPSI byte value of 80: 


FILE ERROR, SCAN TERMINATED 


Errors in the input statements are reported in the following 
format: 


nnnn cc error-message-text 


where: 
nnnn 
Is the sequence number in columns 77 through 80 of 
the card containing the error. 
cc 


Is the column number of the beginning of the input text 
that is in error. This column number is suppressed if the 
error is detected during final validation of all parameters 
for a given field. 


error-message-text 
Is the description of the error as listed in Table B-1. 
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Error message example An example of an input statement error and the resultant error 
message follows: 


Input: 
SEP=, ETAB=EDIT1,KEY=1,LEN=5,POS=0, JUS=X,MAN=Y, 0002 
Error message: 


@002 39 JUSTIFICATION ILLEGAL 


Table B-1 lists alphabetically the message texts inserted into the 
input statement error message. In each case, processing 
continues, unless otherwise indicated in the explanation column. 


Table B-1. Edit Table Diagnostic Messages (Part 1 of 2) 






B TYPE LENGTH GR THAN 4 Four characters (one full word) is maximum 


CARDS NOT IN SEQUENCE Scan terminated, run aborted” 
@ DOUBLE SEPARATOR MISSING Warning only; end-of-file encountered while 


searching for separator 
DUPLICATE NAME Duplicate name for nonpositional field 


FIELD NOT ACCEPTED, KEYS STARTED Positional parameters not allowed after 
nonpositionals started 


FIELD NOT IN SEQUENCE Positional parameters must be in sequence 

FILLER MUST BE SINGLE CHARACTER Self-explanatory 

ILLEGAL FIELD TYPE Only A, B, M,N, or P accepted 

INVALID MAN SPECIFICATION Only Y or N accepted 

INVALID NAME Name too long or contains invalid characters 

INVALID SEPARATOR Scan terminated, run aborted; = and - are not 
allowed as separators” 

JUSTIFICATION ILLEGAL Only R or L accepted 

KEYWORD ETAB MISSING Self-explanatory 

KEYWORD INVALID Self-explanatory 

KEYWORD KEY= MISSING Self-explanatory 

r KEYWORD SEP= MISSING Scan terminated, run aborted* 
LEN OR POS EXCEEDS MAX Maximum length is 255; maximum position is 


32,767 





UP-9206 SPERRY UNIVAC 0S/3 B-14 
IMS ACTION PROGRAMMING IN RPG II 





EDIT TABLE GENERATOR ERRORS 





Table B-1. Edit Table Diagnostic Messages (Part 2 of 2) 





LEN OR POS MISSING 


LEN ZERO 


MAX OR MIN ABSOLUTE VALUE 
TOO LARGE 


N TYPE LENGTH GR THAN 10 


NO DEFAULT FOR THIS FIELD 
NO FIELDS DEFINED 


P TYPE LENGTH GR THAN 16 


REPEATED FIELD 

SEPARATOR CHARACTER MISSING 
SEQUENCE NUMBER NOT NUMERIC 
= SIGN MUST FOLLOW KEYWORD 


TOO MANY FIELDS 


XXX OVERLAPS VYY 


Required parameters 

Length must be at least 1 

23'-1 is largest absolute value allowed 

Ten characters is maximum unless MAX and 
MIN both specified 

Parameter value must be specified 

Empty table not allowed 


Sixteen characters maximum for packed 
decimal field 


Parameter already specified 
Self-explanatory 

Scan terminated, run aborted* 
Seif-explanatory 


Scan terminated, run aborted; output buffer 
overflow” 


Warning only; overlapping fields permitted 


* These errors set the UPSI byte to 80; all other errors in this table result in an UPSI 


byte value of 40. 
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B.6. ENTERING INPUT MESSAGES FROM TERMINAL 


When the terminal operator enters an input message for which 
you've generated an edit table, an IMS component called the 
expanded input editor processes it. The following considerations 
apply when entering input messages from the terminal: 


Transaction code first m= When an input message contains a transaction code, the 
transaction code must always be the first field. If the 
transaction code is less than five characters, enter a space 
before keying in the separator character. 


Beginning positional fields ™ Positional fields begin with the first nonblank character and 
extend to the next separator. Positional fields must appear 
in the same order as specified in the edit table definition. If 

Omitting positional fields you omit a positional field, enter an additional separator 
character in its position. A positional field entered as input 
may not contain an equal sign. 


Keyword fields m Keywords must be followed by an equal sign with no 
intervening blanks. Data starts immediately after the equal 
sign and extends to the next field separator. 


Invalid plus sign = Numeric values are positive unless preceded by a minus 
sign. The plus sign (+) is an invalid character. 


Error messages screen m Error messages are displayed on the first line of the display 

placement terminal; therefore, we recommend that you start input 
messages on the second line so that the input is not erased 
by an error message. 


Continuing fields m If you continue fields from one line to another, IMS 
removes the DICE code at the end of each line and replaces 
it with a blank character, which it sends to the action 
program as part of the data. Always enter on one line 
fields that don’t exceed the width of the screen. If a field 
exceeds the screen width and must be continued from one 
line to another, avoid splitting a word between lines. 


Ending input with positional @  |f the terminal input ends with a positional parameter (no 

parameters keyword parameters are specified), enter a separator 
character at the end of the input message; otherwise, the 
input message could be partially deleted. A correct terminal 
entry is: 


INFOR,BIOLOGY,CLASS2,MARY J. BLISS, 


When terminal input ends with a keyword parameter, this is not 
necessary. 
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B.7. SAMPLE EDIT TABLE APPLICATION USING POSITIONAL AND KEYWORD 
PARAMETERS 


Example edit table input Figure B-3 and Table B-2 describe sample input to the edit table 
generator for an accounts receivable application and the format in 
which the edited input is delivered to the action program. 


SHIP 
ADDRESS AMOUNT NUMBER 


SEP=,ETAB=EDIT1,KEY=1,LEN=5, POS=0, MAN=Y, 

KEY=2,LEN=20, POS=5, FIL=,JUS=L,MAN=Y, 

KEY=3, LEN=40,PO0S=25,FIL= ,JUS=1, 

KEY=AMT,LEN=4, POS=65, MIN=1000, TYP=B,MAN=Y,FIL=0,JUS=R, 





Figure B~3. Sample Input to Edit Table Generator and Format of Input Delivered to 
Action Program 


Table B-2. Description of Sample input to Edit Table Generator (Part 1 of 2) 






SEP=, The field separator is a comma for both the edit 
specification and input from the terminal. 


ETAB=EDIT1 The edit table name is EDIT1. 


KEY=1 The first field described is positional. It must be the first 
field in the input message. 


LEN=5 The edited field is five characters long. 

POS=0 In the edited message the field begins in position O. 

MAN=Y The field must be present for the message to be 
acceptable. 

KEY=2 The field is positional. It must be the second field in the 


input message. 


LEN=20 The edited field is 20 characters long. 

POS=5 In the edited message the field begins in position 5. 
FIL= The field is to be blank filled in the edited message. 
JUS=L The field is to be left-justified in the edited message. 


MAN=Y The field must be present for the message to be 
acceptable. 





UP-9206 SPERRY UNIVAC OS/3 B-17 
IMS ACTION PROGRAMMING IN RPG Il 


SAMPLE EDIT TABLE APPLICATION 


Table B-2. Description of Sample Input to Edit Table Generator (Part 2 of 2) 






KEY=3 


LEN=40 
POS=25 
FIL= 
JUS=L 


KEY =AMT 


LEN=4 
POS=65 


MIN= 1000 


TYP=B 


MAN=Y 
FIL=O 
JUS=R 


KEY=SN 
LEN=6 
POS=69 
FIL= 


JUS=R 


The field is positional. It must be the third field in the input 
message. 


The edited field is 40 characters long. 

In the edited message the field begins in position 25. 
The field is to be blank filled in the edited message. 
The field is to be left-justified in the edited message. 


The field is a keyword field. AMT=n must be specified in 
the input message. 


The edited field is four characters long. 
In the edited message the field begins in position 65. 


The minimum level allowed for the message to be 
acceptable is $10.00 (entered as 1000). 


In the edited message the field is to be converted to binary. 


The field must be present for the message to be 
acceptable. 


The field is to be zero filled in the edit message. (This 
parameter could have been omitted.) 


The field is to be right-justified in the edited message. (This 
parameter could have been omitted.) 


The field is a keyword field. 

The edited field is six characters long. 

In the edited message, the field begins in position 69. 
The field is to be blank filled in the edited message. 


The field is to be right-justified in the edited message. (This 
parameter could have been omitted.) 


End of edit definition. 
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Terminal input 


Edited message received 
by action program 


Terminal input 


Edited message received 
by action program 


Explanation 


Terminal input 


Output message 


Explanation 


The following examples show freeform input from the terminal 
and the resulting messages sent to the action program in 
accordance with the edit table specifications or, in case of error, 
the output message displayed at the terminal. Note that in the 
edited messages, the 4-character binary field specified for the 
AMT entry is represented by an underlined, 4-hexadecimal-digit 
field. Spaces between each delimiter and the first character of 
the next field are ignored. 


Example 1: 


PAYMT, JOHN D. SMITH,1112 BREEZE DR. PHILA.PA. 19160, 
AMT=2500, SN=123456 


PAYMT JOHNAD. ASMITHAAAAAAA1112ABREEZEADR. APHILA. APA. 
A1916BAAAAAAAAOIC4123456 


Example 2: 


PAYMT, JOHN D. SMITH, ,SN=123456,AMT=2500 


PAYMTJOHNAD.. ASMITHAAAAAAAAAAAAAAAAAAAAAAAAAAA 
AAA AAA AAAAAAAAAAAAAAONIC4E 123456 


The address field wasn't specified as mandatory in the edit 
table input and is omitted here; an additional comma is 
coded in its position. The AMT and SN fields are keyword 
fields and need not be entered in the order defined in the 
edit table input. 


Example 3: 


PAYMT ,JOHN D. SMITH, 1112 BREEZE DR. PHILA. PA. 19160, 
AMT=2500, SN=123456 


ILLEGAL INPUT 


The transaction code field is longer than the LEN 
specification. 
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Terminal input 


Output message 


Explanation 


Terminal input 


Output message 


Explanation 
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Example 4: 


PAYMT, JOHN D. SMITH,1112 BREEZE DR. PHILA. PA.19160, 
AMT=700, SN=123456 


AMT IS BELOW MIN 


Edit table specifies AMT must be at least 1000. 
Example 5: 


PAYMT, JOHN D. SMITH,1112 BREEZE DR. PHILA. PA. 19160, 
SN=123456 


AMT MISSING 


AMT was specified as mandatory. 
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Appendix C. Summary of IMS 
Error Codes 


This appendix presents all the error codes returned by IMS as a 
result of function calls made by action programs. 


Completion status codes Table C-1 lists and defines the values returned to the 
status-code field of the program information block. This value 
indicates the completion status of the function request. 


Defined record management Table C-2 lists and describes values returned to the 
Status: codes detailed-status-code field with status code 1 (invalid key) when 
errors occur on a defined file. 


Invalid request status codes Table C-3 lists and describes values returned to the 
detailed-status-code field when the status code returned is 3 
(invalid request). 


Internal message control Table C-4 lists and describes values returned to the 
status codes detailed-status-code field when the status code returned is 6 
(internal message control error). 


Screen formatting status Table C-5 lists and describes values returned to the 
codes detailed-status-code field when the status code is 7 (screen 
format services error). 
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Table C-1. Values Returned to the Status-Code Field after Function Requests 


Successful 


Invalid key or record number 






End of file or unallocated optional file 
Invalid request 

1/O error 

Violation of data definition 
Internal message control error 


Screen format error 
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Table C-2. Detailed Status Codes for Defined Record Management Errors 
(Invalid Key — Status Code 1) 












No identifier supplied Insert an IDENTIFIER statement in 
the item definition. 

Identifier too long Identifier may be from 1 to 30 
alphanumeric characters tong. 


Value entered at terminal isn't in 
range of VALUE clause specified. 


Identifier out of range 
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Table C-3. Detailed Status Codes for invalid Requests (Part 1 of 2) 


Incorrect number of parameters Please submit a software user 
report (SUR) or contact your 
Sperry Univac representative. 


Function code out of legal Please submit a SUR or contact 
range your Sperry Univac representative. 


Incorrect parameter value Please submit a SUR or contact 

your Sperry Univac representative. 
Shared record not in use by This code does not apply to user 
this transaction action program requests. 


File not defined A file named in a request to IMS 
was not defined at configuration. 


File not open A file named in a request to IMS 
was closed by the master terminal 
(ZZCLS) or by data management as 
the result of an unrecoverable error. 


Function invalid for type The function specified in a 
of file request to IMS is not valid for 
the type of file named. For 
example, a SETLL for a nonindexed file. 





Record(s) not locked Please submit a SUR or contact 
your Sperry Univac representative. 


Function sequence for an Input did not precede output. 
update operation is invalid 


Illegal function requested The requested function is not 
consistent with the DTF or RIB 
parameters in the configuration. 


File not assigned to this Same as code 05 
action 


Required module not included A request was made to IMS that 

in configuration required a module not included in 
the IMS load module at 
configuration. 


Capacity exceeded on ADD A request was made to add a record 
operation to a MIRAM or ISAM file, but there 
wasn't sufficient space. 


Insufficient space in main User must allocate more main 
storage storage space. 


Update not permitted in A request was made to perform some 
configuration update function, but this update 
was disallowed at configuration. 
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INVALID REQUEST ERROR CODES 


& Table C-3. Detailed Status Codes for Invalid Requests (Part 2 of 2) 














Update suppressed for files The requested update is not 
permitted because of an I/O error 
in the audit file, a file used for 


online recovery. 







Trace file down File recovery is not operational; 
no updates are allowed. Only file 


displays are allowed. 





Record locked by another 
transaction (single-thread 
only) 


Under single-thread, an action 
tried to add or update a record, 

but the record was already locked 
by another transaction. 
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INTERNAL MESSAGE CONTROL ERROR CODES 





Table C-4. Detailed Status Codes for Internal Message Control Errors (Status Code 6) 












Destination terminal Output-for-input queueing was requested and 
busy, on hold, or down 


aS 






1. destination terminal is in interactive mode; 
2. destination terminal has an input message on queue; 


3. ZZHLD or ZZDWN command was entered for destination 


terminal; 
4. destination terminal is marked physically down to ICAM; or 
5 IMS cannot allocate main storage buffer (multithread only; 


INBUFSIZ specification inadequate. 


Destination terminal SEND function was issued for message switching. Message is 
physically or logically queued at destination terminal and ts transmitted when terminal 
down; message queued becomes operational. 










Invalid destination terminal-id or auxiliary-device-id; or, aux-function 
field contains X'C3', X’F3’, or X'F7’ (not valid with SEND function). 


Invalid specification 
in output message header 







No ICAM network buffer Insufficient buffer space was allocated in ICAM network definition, 


available 







Output error occurred on attempt to write a message to disk; error 
was passed to IMS by ICAM. On output to console, this error 
occurs when console is physically or logically down. 


Disk error, or recoverable 
system error on output 
to console 







In delayed internal succession or output-for-input queueing, output 
message length was larger than the input buffer pool. 






Invalid length specification 


































































Validation error; all error 
fields in variable data area 
are replaced by hexadecimal F's. 


Format area not large enough; 
IMS places actual length 
required for format in the 
text-length field 


Variable data area not large 
enough 


Screen format can't be 
displayed because no terminal 
slots are available 


Variable fields specified for 
input-only format 


Format dimensions are greater 
than screen dimensions 


Fatal error; 1/O error reading 
format file 


Data description in action 
program doesn't match screen 
format generation 


SFS failed 


SFS failed during input 
conversion 


IMS error 


Screen format can’t be 
transmitted because this 
is a program-initiated 
DDP transaction. 
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SCREEN FORMATTING ERROR CODES 


Table C-5. Detailed Status Codes for Screen Formatting Errors (Status Code 7) 


Variable data fields don’t 
match specifications at 
screen format generation. 


OUTSIZE=n specification 
in ACTION section of 
configuration isn't large 
enough. 


WORKSIZE=n specification in 
ACTION section of configuration 
isn’t large enough. 


SFS=n specification in 
OPTIONS section of 
configuration isn't large 
enough. 


Screen format was designed 
for input only. 


Screen format is larger 
than source terminal screen. 


Get DM error message from 
console; refer to system 
messages programmer/reference, 
UP-8076 (current version). 


Screen format was 
incorrectly generated. 


System error; take dump and 
write software user report 
{SUR). Can also occur if format 
contains protected fields and 
terminal doesn’t have protect 
feature or isn’t in protect 
mode. 


Inadequate main storage in 
system; or format contains 
protected fields and terminal 
doesn’t have protect feature or 
isn't in protect mode. 


Take IMS job dump and submit SUR. 


Action program processing 
DDP transaction attempted 
to send screen format to 
initiating action program. 
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General coding restrictions 


Coding restrictions for 
random files 


Coding restrictions for 
sequential files 
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ACTION PROGRAM CODING RESTRICTIONS 


Appendix D. Action Program 
Coding Restrictions 


Table D-1 is a summary of coding restrictions for all the RPG Il 
coding forms. 


Table D-2 summarizes allowable entries on the file description 
form for random access, MIRAM, ISAM, DAM, and defined files. 


Table D-3 summarizes allowable entries on the file description 
form for sequential MIRAM and SAM files. 
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ACTION PROGRAM CODING RESTRICTIONS 


Table D-1. IMS Restrictions for RPG !1 Coding 


H Control card specifications 8 Error analysis dump 


9 Operator control 
15 Generate debug code 
41 First page forms alignment 






File description specifications File type (C and D not allowed) 
Table and array file designation (T)O 
Block length (Same as record length) @ 


File organization: 


ADDROUT (D) © 

Record address (blank) © 
Additional 1/O areas® 
Sequential MIRAM and SAM tape/disk input files 
ISAM and indexed MIRAM output files 


Device: 


CTLRDR 
READER 

CRP 

PUNCH 
CONSOLE 
PRINTER 
WORKSTATION 
REMOTE FILES 


Labels @ 

Name of label exit option®@ 

Size of ISAM index entry@ 
Unordered load 

Cylinder overflow space percentage® 


Number of extents @ 
Tape rewind® 


a ay eens eae 


E Extension specifications © Chaining (C1-C9) tables or arrays 


I Spread card feature (TR) 
42 Stacker select 

Cc Display operation (OSPLY) 

cc 


NOTES: 
® Used only with nonindexed MIRAM and DAM files. 


® Ignored by RPG I! compiler; must be specified in IMS configuration. 
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ALLOWABLE FILE DESCRIPTION SPECIFICATIONS 


Table D-2. Allowable File Description Specifications for ISAM, MIRAM, DAM, 


File description form 
entries for ISAM, MIRAM, 
DAM, and defined files 


and Defined Files 


BS: 


boa Type (Column 6) 

File Name (Column 7-13) 
File Type (Column 15) 

File Desgination (Column 16) 
Format (Column 19) 


Record Length (Column 24-27) 






F 


User-defined name 
|, U, or O 

S, R, C, D, or P 

F 


User's record size 


Mode of Processing (Column 28) L, R, or blank 
Key Field Length (Column 29-30) 01-99 @ 
Record Address Type (Column 31) AorP 
ok 2 
File Organization (Column 32) I 
Sek 
 ) Key Field Start Position 0001-9999(1) 


(Column 35-38) 
Device (Column 40-46) 


File Addition (Column 66) 


Must be disk device 


Blank or A 


NOTES: 
@ Indexed files 


@ Nonindexed (relative) files 


@ Sequential processing 
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ALLOWABLE FILE DESCRIPTION SPECIFICATIONS 


Table D-3. Allowable File Description Specifications for Sequential MIRAM 
and SAM Output Files 


File description form 
entries for sequential 
MIRAM and SAM files 





Form Type (Column 6) F 

File Name (Column 7-13) User-defined name 

File Type (Column 15) 0 

Format (Column 19) F 

Record Length (Column 24-27) User's record size 

Overflow Indicator (Column 33-34) May be specified for line counter files 
Line Counter (Column 39) Blank or L 

Device (Column 40-46) Must be disk or tape device 














UP-9206 


Term 


Abnormal termination 
after SEND function 
involuntary 
voluntary 


Absolute addresses 
Action 
Action program routing 


Action programs 
coding description 
coding restrictions 


compile 


debugging 

differences from other RPG Il 
programs 

example execution 


identification 
internal subroutines, use 
link 


load area in snap dump 


preparations for online processing 
processing 

recompiling 

reusable code 

scheduling 

store 


using screen formats 
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Reference 


5.14 

2.6 

2.6 

Table 2-4 


Fig. 9-1 
13 


72 


2.1 

Table D-1 
Appendix D 
8.2 

Fig. 8-3 
Fig. 8-4 
Section 9 


3.1 
3.6 
Fig. 3-3 
2.2 
45 
8.3 
Fig. 8-6 
Fig. 8-7 
9.8 
Fig. 9-1 
8.1 
3.6 
85 
15 
3.3 
8.4 
Fig. 8-9 
4.2 


Page Term 


Activate function 


5-44 Activation record 
2-13 description 
2-13 main storage layout 
2-12 

Allocation map 
9-2 contents 

locating in snap dump 

a Array, example of use 
7-3 
2-1 Auto transmit feature 
D-2 

Aux-device-no field, OMA 
8-2 continuous output use 
8-3 description 
8-3 aut 

Aux-function field, OMA 

continuous-output use 

3-1 description 
3-6 print/transfer options 
3-7 read/search options 
2-1 settings 
4-17 
8-4 
8-5 Auxiliary device 
8-5 aux-device-id field 
9-10 aux-function field settings 
9-2 condition codes 
8-1 continuous output 
3-5 identification 
8-8 supported 
1-9 supporting DICE codes 
3-2 transmitting formatted screens 
cs Auxiliary-device-id, IMA header 
4-1 


index 1 


Index 


Reference 


75 
Fig. 7-2 


16 
1.6 


9.4 
9.8 


5.2 
5.3 
Fig. 5-1 


5.12 


5.6 
2.12 


5.6 
2.12 
5.6 
5.12 
Table 5- 
Table 5 


2.12 
Table 5-2 
Table 5-5 
5.6 


5.6 
Table A-3 
6.11 


2.9 


Page 


UP-9206 SPERRY UNIVAC 0S/3 Index 2 
IMS ACTION PROGRAMMING IN RPG II 











Term Reference Page Term Reference Page 
B Compiling and linking action programs Section 8 
Backward-one-block option, Console, sending messages 5.20 5-54 
cassette/diskette 5.12 5-42 
Continuity data area 
Binary or packed field lengths, edit as input file 2.16 2-40 
table generator B.3 B-7 continuity-data-input-length 2.6 2-17 
continuity-data-output-length 2.6 2-17 
definition 2.15 2-38 
Table 2-9 2-38 
file 2.16 2-41 
flow of saved data 2.16 2-41 
input form coding 44 4-14 
Cc passing data 2.16 2-39 
purpose 44 4-14 
Calculations size for successor 2.17 2-43 
continuous output example 5.10 5-26 update file 2.16 2-40 
for continuity data area 44 4-15 Fig. 2-14 2-40 
for multiple output messages 5.2 5-4 updated at output 44 4-16 
sample program calculations 3.19 3-22 use, example 44 4-14 
used to control processing 44 4-15 
Cassette/diskette varying size 2.17 2-41 
print/transfer options 5.6 5-11 Fig. 2-3 2-20 
read/search options Table 5-6 5-40 
5.12 5-40 Continuity-data-area-inc, PIB 
search arguments Table 5-7 5-42 description 2.6 2-7 
moving value 2.17 2-42 
CDA See continuity 
data area. Continuity-data-input-length, PIB 
description 2.6 2-7 
Coding for action programs determining value 2.17 2-41 
calculation form 3.19 3-22 
CDA size specification on output Continuous output 
form Fig. 2-17 =. 2-43 cassette/diskette 5.12 5-40 
control form program-id 2.2 2-1 cassette/diskette search arguments Table 5-7 5-42 
file description specifications 2.1 2-1 coding 9.6 5-9 
input message, pass data 2.11 2-28 configuration specification 5.4 5-9 
Fig. 2-8 2-28 continuous-output-code field 5.8 5-18 
input message area, reading 2.10 2-27 delivery code 5.8 9-18 
Fig. 2-7 2-27 devices receiving 5.5 5-9 
interface areas 2.3 2-3 example program 9.11 5-29 
naming action programs 2.2 2-2 Fig. 5-9 5-29 
output form 3.20 3-22 example program (SALES2) 5.10 5-24 
output message area, file Fig. 5-7 5-24 
description 2.13 2-33 example with print transparent 
Fig. 2-9 2-33 and inhibit space suppression Fig. 5-4 5-14 
output message area, output example with transfer all option Fig. 5-3 9-13 
form coding Fig. 2-11 2-36 function key use 5.9 5-21 
Fig. 2-12 2-36 generating messages 5.4 5-9 
program information block 2.5 2-7 5.10 5-27 
27 2-20 input message return to successor 
2.8 2-23 program Fig. 5-6 5-18 
screen format coding 47 4-20 limitations 5.7 5-14 
message transmission 5.7 5-15 
Communications output printer, receiving output-for-input queueing 5.15 5-46 
DICE codes Table A-1  A-6 output only screens 6.6 6-6 
: print/transfer options Table 5-3 5-11 
program example 5.10 5-23 
5.11 5-29 
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& Term 


Continuous output (cont) 


read/search options 

recovery 

restrictions for use with DDP 
status codes 

successor program 


terminal screen size 
termination 
to terminal 


used with cassette/diskette 
using aux-device-no field 
using aux-function field 


Continuous-output-code, OMA 
description 
how used 


passing it 
when not specified 


CONTOUT parameter, IMS configuration 
continuous output 
output-for-input queueing 


Control form 
coding 
entries 


coP 


CRT devices, receiving DICE codes 
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Reference Page 


Table 5-6 5-40 
5.9 5-21 
73 7-6 
5.8 5-18 
5.7 5-15 
5.10 5-27 
5.10 5-28 
5.10 5-27 
5.6 5-10 
Fig. 5-2 5-10 
5.12 5-40 
5.7 5-14 
5.7 5-13 
2.12 2-32 
5.8 5-18 
Fig. 5-5 5-1 
5.10 5-27 
5.12 5-43 
5.4 5-9 
5.13 5-44 
2.2 2-2 
3.8 3-11 


See communications 
output printer. 


AS A-10 
Table A-1 — A-6 


Term 


Data-def-rec-name 

Data files 

Data type 

Date-time stamp, IMA header 
DDP-mode field, PIB 


Debugging 


Defined file name 
Defined files, identifying 
Defined record area (DRA) 


Delayed internal succession 
description 
output only screens required 


Delivery notice code, continuous output 

before line disconnect 

definition 

interrogation 

status returned 

status returned for auxiliary 
devices 

unsuccessful 


Destination-terminal-id, OMA 
description 
locating tn snap dump 


Detailed status codes 

defined record management 
(status code-1) 

internal message control 
(status code-6) 

invalid requests (status code-3) 

1/0 error (status code-4) 

location in snap dump 

reading 

screen formatting (status code-7) 


Device independent control expressions 
auxiliary devices 
coordinate value interpretations 
description 
formats 
functions 
functions performed 


Index 3 


Reference 


2.6 
See files. 
B.3 
2.9 
2.6 


See dump, 
snap. 


2.6 
2.6 


Fig. 1-9 


14 
6.6 


5.19 

5.8 

5.10 
Table 5-4 


Table 5-5 
5.10 


2.12 
9.6 


Table C-2 


Table C-4 
Table C~3 
2.6 
9.5 
2.7 
Table C-5 


Table 
Table 
Al 
A4 
Table A-1 
A.2 


Page 


2-16 
2-16 


1-10 
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Term Reference Page Term Reference Page ®@ 
Device independent control expressions (cont) 
interpretation A5 A-9 edited 92 9-1 
macroinstructions Table A-1 —A-6 error code interpretation 9.5 9-8 
primary devices Table A-2 A~10 finding error in PIB 95 9-8 
stripping A2 A-3 function call, determining last 9.8 9-11 
terminals supporting AS A-10 function calls, hexadecimal 
use in action program A6 A-12 equivalent Table 9-1 9-12 
Fig. A-3 A-12 interface area, order 9.9 9-13 
Fig. A-4 A-12 locating *ERROR in snap dump 9.5 9-8 
use in message formatting A.2 A-1 Fig. 9-8 9-28 
use with ICAM A3 A-4 main storage layout 9.3 9-2 
parameter list location 9.8 9-12 
Dialog transaction 13 1-4 PIB field locations 9.5 9-9 
registers saved by involuntary 
DICE See device snap 9.3 9-3 
independent control registers saved by voluntary snap 9.3 9-3 
expressions. sample Fig. 9-3 9-6 
save area 9.4 9-5 
Directory routing 7.2 7-3 single and multithread formats 9.9 9-13 
status code location 9.5 9-8 
Disconnecting tine from action program See line successor-id field location 95 9-8 
disconnect. terminal control table Fig. 9-6 9-20 
termination indicator field 
Diskette/cassette location 9.5 9-9 
auto-transmit feature 9.12 5 termination indicator to obtain 
print/transfer options 5.6 5 dump 2.6 2-11 
read/search options 5.12 5-41 thread control block Fig. 9-4 9-14 
Table 5-6 5-40 Fig. 9-5 9-18 
search arguments Table 5-7 5-42 thread control block use 9.9 9-13 
types 9.2 9-1 
Display constants, output to screen 6.6 6-5 use of input message area 97 9-10 
Fig. 6-2 6-13 use of output message area 9.6 9-9 
use of program load area 9.8 9-10 
Distributed data processing 
action program requirements 7.1 7-1 Dynamic main storage 
action program succession 7.4 7-7 building screen 6.8 6-8 
local IMS 7.1 7-2 Fig. 6-4 6-8 
locap name 7.1 7-2 description 6.4 6-2 
operator-initiated remote 
transaction 7.4 7-7 
primary IMS 7.1 7-1 
program-initiated remote 
transaction 75 7-8 
remote IMS 7.1 7-2 
remote transactions 7.3 7-5 
routing remote transactions 7.2 7-3 
secondary IMS 71 7-2 
terminology 7.1 7-1 
DTF, locating in snap dump 9.8 9-12 
Dump, snap 
allocation map 9.4 9-5 
analysis 9.4 9-5 
conditions 9.1 9-1 
debugging resources 9.10 9-25 
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@ Term 


Edit table generator 

coding for input 

description 

diagnostic messages 

duplicate edit table name 

entering input messages from 
terminal 

error processing 

execution 

parameters 

sample parameter description 

transaction codes smaller/larger 
than five characters 

UPS! byte values 

use of positional and keyword 
parameters 


Edit table name 
Edited directory, snap dump 


Edited field length 


@ ERET parameter 
configured 
specified when using SEND function 


Error codes, IMS 
See also status codes and detailed 
status codes. 


Error message file 
generating error messages 
sample use 


Error messages, displaying 


Error processing 

detailed status codes 

ERET configurator parameter 

*ERROR field 

*ERROR location 

output-for-input queueing 

status codes 

See also dump, error codes, 
status codes, or detailed 
status codes. 


Error status 
codes 
how to determine 
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Reference 


B.2 
B.1 
Table B-1 
B.4 


B.6 
B5 
B.4 
B.3 
Fig. B-1 


B.3 
B.4 


B.7 
B.3 
9.2 
B.3 
2.6 
5.18 


Appendix C 


46 
46 


47 


2.6 
2.6 
9.10 
9.5 
5.14 
2.6 


Appendix C 
2.6 





Page 


4-20 


2-9 


Term 


ETAB 


Examples of action programs 
JAADD! program (file update and 
internal subroutines 
JAMENU program (screen updates) 
LSTLIM program (multiple output 
message) 


NCSC program (continuous output) 


RCCUST program (file update) 
RCMENU program 
SALES2 program (continuous output) 


transaction with external succession 


External succession 
description 
sample program 
to continue generating continuous 
output 


Fast load feature 
fast load file 
store action programs 


FCC 


Field control characters 
ASCII characters used 


format 
use in action programs 


Field justification, edit table generator 


Field separator character, edit table 
generator 


Field starting position, edit table 
generator 


FIL 


Index 5 


Reference Page 


See edit 

table name. 

4 3-. 4-2 
4.1-.2 4-2 

Fig. 5-1 5-2 
Fig. 5-2 5-10 
Fig. 5-9 5-29 
Fig. 5-10 5-44 
3.5-.20 3-3 

3.5-.13 3-4 
5.10 5-23 
Fig. 5-7 5-24 
3.4-.9 3-2 

14 1-5 

3.4 3-2 

57 5-15 
8.4 8-7 

8.4 8-7 

See field 


control characters. 


Table A-4 = A-14 
Table A-5 A-15 
A7 

AJ 

B.3 B-8 
B.2 B-8 
B.3 B-7 


B.3 B-5 
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Term Reference Page Term Reference 
File description specifications | 
allowed for ISAM, MIRAM, DAM, 
and defined files Table D-2  D-3 IMA See input 
allowed for sequential MIRAM and message area. 
SAM output files Table 0-3 = D-4 
coding action programs 23 9-3 Immediate internal succession 
coding restrictions Table D-1 D-2 description 14 1-8 
continuity data area 44 4-14 Saves interface areas 2.11 2-29 
continuous output sample program 5.10 5-25 
input demand file 27 2-20 Indicators, RPG Il, setting 3.12 3-15 
input message area 2.9-.11 2-25 Table 3-1 3-15 
multiple output messages 5.2 5-3 
output message area 212-14 2-30 Initiating transactions 3.3 3-2 
update demand file 2.8 2-23 
Input demand file 
File extension form continuity data area 2.16 2-40 
coding restrictions Table D-1 D-2 input message area 2.9-.11 2-25 
multiple output messages 5.2 5-3 program information block 2.7 2-20 
2.5 2-7 
Files sample file description form 
accessible 23 2-4 coding 27 2-20 
accessing sequential files 2.3 2-3 sample’ input form coding 27 2-21 
allowable file description entries Appendix D 
assigning interface area file names 24 2-6 Input fields, entered on screen format 6.6 6-5 
coding restrictions Table D-1 0-2 Fig. 6-2 6-5 
defined, identification 2.6 2-16 
describing in action program 2.3 2-3 Input message 
PIB file type depends on use 25 9-7 formatted screens for input 6.7 6-7 
types used by action programs Table 2-1 2-3 formatting using DICE A2 A-3 
updating restrictions 23 2-4 locating in snap dump 9.7 9-10 
receiving in remote transaction 73 7-5 
Fill character identification, edit returned to successor in 
table generator B.3 B-8 continuous output Fig. 5-6 5-18 
Formatted screens See screen Input message area 
format services. auxiliary-device-id 2.9 2-26 
control header format Table 2-7 = 2-25 
Function calls date-time stamp 29 2-25 
determining last from snap dump 9.8 9-11 defining as input file 29 2-25 
error returns Appendix C definition 29 2-25 
hexadecimal equivalents Table 9-1 9-12 input fields, defined 3.18 3-21 
passing data 2.11 2-28 
Function keys, used in continuous output 5.9 5-21 reading 2.10 2-2] 
3.11 3-13 
sample use 3.11-.12 3-13 
snap dump 9.7 9-10 
source-terminal-id 2.9 2-26 
text-length 2.9 2-26 
H Input options, cassette/diskette 
read 5.12 5-41 
Header, control See program read transparent 5.12 5-41 
information search and read 5.12 5-41 
block, input search and read transparent 5.12 5-41 
message area, 
or output “ 


message area. 
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@ Term 


Input specifications form 
coding restrictions 
continuity data area 
continuous output 
multiple output messages 


Interface areas 
action program 
activation record 
coding 
continuity data area 
defined record area 
definition 
example coding, RCCUST 
example coding, RCMENU 
examples defining 
input message area 
layout in snap dump 


order in snap dump 

output message area 

program information block 

relationship to thread control 
block 


@& Internal subroutines 


Internal succession 
delayed 
immediate 


Invalid request 
detailed status codes 
status code 3 


1/0 error, status code 4 


Job control 
compile and link action program 


compiling action program 


edit table generator execution 
@ link editing action program 
recompiling and linking action 
program 
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Reference 


Table D-1 


44 
5.10 
5.2 


16 
16 
2.3 
2.15 
1.6 
24 
3.17 
3.9 


3.9-. 


2.9 
9.3 
Fig. 
9.9 
2.12 
2.5 


Fig. 


45 


14 
14 


Appendix C 


2.6 


2.6 


Fig. 
Fig. 
Fig. 
Fig. 
Fig. 
Fig. 
Fig. 
Fig. 
Fig. 


Fig. 


17 


9-1 


9-2 
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Term Reference 
Job streams See job 
control. 
JUS specification, edit table generator B.3 
K 

KEY field identification, edit table 

generator B.3 
KEY specification, edit table generator B.3 


L 


LEN specification, edit table generator B.3 
Line disconnect 
coding example 5.15 
delivery notice before 5.19 
description 5.19 
Link jproc 8.3 
Fig. 8-5 
Link map, for debugging 9.10 
Fig. 9-7 
Load module, naming 8.3 
Local IMS, definition 71 
Locap name, definition 7.1 


Lock-roliback indicator, PIB 


default value 2.6 
description 2.6 
locating in snap dump 9.5 
online file recovery 2.6 
Locking 
for update 2.6 
holding locks 2.6 
online file recovery 2.6 
record 2.6 
releasing locks for action Table 2-6 
releasing locks for transaction Table 2-6 
rollback indicators Table 2-6 


Page 


B-8 


B-6 


B-5 
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Term Reference Page Term 


M O 
MAN, specification edit table generator B.3 B-8 OMA 
Mandatory field, edit table generator B.3 B-8 
Master workstation 5.20 5-54 Operator routing 
MAX specification, edit table generator B.3 B-8 Output-for-input queueing 
coding 
Maximum value limitations, edit table coding example 
generator B.3 B-8 configuration 
definition 
Message-length field, locating in identifying terminal for output 
snap dump 9.6 9-10 message 
initiating transaction at another 
Message size specification 2.6 2-16 terminal 
with continuous output 
Message switching with screen bypass device 
coding required 5.17 5-47 
Fig. 5-13 5-48 Output message area (OMA) 
output only screens required 6.6 6-6 building screen formatted messages 
switch transaction 5.17 5-47 coding 
continuous-output-code 
MIN specification, edit table generator B.3 B-8 control header format 
definition 
Minimum value limitations, edit table destination-terminal-id 
generator B.3 B-8 file specifications 
sample use 
Multiple output messages SFS-location 
operator response 5.3 5-8 SFS-type 
sample use 5.2 5-1 snap dump 
5.3 5-5 text-length 
Fig. 5-1 5-2 
using SEND function 53 5-6 Output message header 
field descriptions 
Multithread snaps See thread format and contents 
control 
block. Output messages 
continuous output 
continuous output recovery 
returned on unsuccessful 
delivery notice code 
N delivery notice status codes 
determining output message length 
Naming programs 2.2 2-2 for input queueing 
formatting using DICE or FCC 
Nonpolled device acknowledgment 5.9 5-21 generating multiple 
Normal termination 14 1-6 line disconnect 


multiple, generating 
multiple, processing 
output-for-input-queueing 
queueing 


Reference 


See output 
message 
area. 


7.2 


5.14 
Fig. 5-12 
5.13 
9.13 


5.14 


5.16 
5.15 
5.16 


6.4 
2.14 
2.12 
Table 2-8 
2.12 
2.12 
2.13 
3.13 
2.12 
2.12 
9.6 
2.12 


2.12 
Table 2-8 


5.4-.12 


5.9 

5.11 
Table 5-4 
2.14 
5.13 

A.2 

5.2 

5.3 

5.19 

5.2 

5.3 
5.14.16 
5.3 
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Output messages (cont) 
recovery with continuous output 5.9 5-21 Print transparent with UNISCOPE 100 5.6 5-12 
sample coding 3.20 3-22 
sample generation 3.13 3-16 Printer 
sample output coding 3.20 3-23 continuous output 5.5 5-8 
screen formatted 6.6 6-5 effect with inoperative delivery 
switching 5.17 5-47 notice code 5.10 5-26 
to system console 5.20 5-54 writing formatted screens 6.11 6-12 
types 5.1 5-1 
when none generated 3.13 3-17 Program information block (PIB) 
coding forms for updating 2.8 2-24 
Output specifications form Fig. 2-5 2-23 
continuous output 5.10 5-26 Fig. 2-6 2-24 
multiple output messages 5.2 5-5 contents (format) Table 2-3 2-8 
sample use 5.13 5-44 continuity-data-area-inc 2.6 2-17 
screen format messages 6.6 6-5 continuity-data-input-length 2.6 2-17 
continuity-data-output-length 2.6 2-17 
data-def-rec-name/defined filename 2.6 2-16 
DDP mode 2.6 2-19 
DDP-mode field 7.3 7-5 
defining fields 3.14 3-18 
definition 2.5 2-7 
device name 27 2-21 
input form entries for reading 2.7 2-21 
lock-rollback indicator 2.6 2-14 
purpose and use 2.6 2-9 
© P read 27 2-20 
reading 2.7 2-20 
Packed or binary field lengths, edit sample use 3.14 3-18 
table generator B.3 B-7 setting successor-id and 
termination type 3.14 3-18 
Parameter list, snap dump 9.8 9-12 snap dump 9.9 9-8 
source-term-attributes 2.6 2-18 
Passing data source-term-msg-line-length 2.6 2-18 
continuity data area 2.16 2-39 source-term-msg-number-lines 2.6 2-18 
input message area 2.11 2-28} Source:-terminal:type 2.6 2-18 
output message area 2.14 9-35 standard-msg-line-length 2.6 2-16 
standard-msg-number-lines 2.6 2-17 
PIB See program status code and values 2.6 2-9 
information success-unit-id 2.6 2-17 
block. successor-id 2.6 2-17 
termination indicator 2.6 2-11 
Polled device, acknowledgment 5.9 5-21 testing status/detailed status 
codes Fig. 2-4 2-21 
POS specification, edit table generator B.3 B-7 transaction-id 2.6 2-16 
update 2.8 2-24 
Primary IMS, definition 71 7-1 3.14 3-18 
updating 2.8 2-23 
Print form (ESC H) Table 5-3 5-11 work-area-inc 2.6 2-17 
work-area-length 2.6 2-17 
Print mode Table 5-3 -1l 
56 5-11 Program name, assigning 3.8 3-11 
3.16 3-20 
@ Print/transfer options Table 5-35-11 
Print transparent mode 5.6 5-12 
Table 5-3 5-11 
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Term Reference Page Term Reference Page & 
Ss 
Queueing messages 53 5-6 Sample action programs See 
examples 
of action 
programs. 
Save area, snap dump 9.4 9-5 
Saving data 
Read option, cassette/diskette 5.12 5-41 continuity data area 2.16 2-41 
input message area 2.11 2-28 
Read/search options output message area 2.13 2-34 
description 5.12 5-40 
settings for aux-function field Table 5-6 5-40 Scheduling programs, contents of 
main storage 3.10 3-13 
Read transparent option 5.12 5-41 
Screen bypass 
RCCUST sample program 3.15-.20 3-20 output-for-input queueing 5.16 5-46 
with cassette/diskette 5.12 5-43 
RCMENU sample program 3.5-.13 3-3 
Screen format services 
Record key, saving next 5.11 5-38 coding required 6.8 6-8 
coding to build screens 47 4-20 
Record length, for PIB 2.7 2-20 6.8 6-8 
Fig. 4-2 4-3 
Record locking 2.6 2-14 configuration requirements 6.4 6-2 
devices used 6.2 6-1 
Register section, snap dump displaying screen formats 6.1 6-1 
location 9.3 9-3 distributed data processing 7.6 7-9 
more than one set 9.3 9-3 error codes 6.10 6-11 
one set 9.3 9-3 Table 6-1 = 6-11 
9.4 9-5 formatted screens for input 6.7 6-6 
function keys to cancel screens 6.6 6-6 
Relative main storage addresses Fig. 9-1 9-2 generated offline 6.3 6-1 
9.3 9-2 generating screen formats 6.3 6-1 
IMS start-up requirements 6.5 6-3 
Remote IMS, definition 7.1 7-1 invalid input 6.7 6-7 
output screen with no variable data 6.9 6-10 
Remote transactions See OUTSIZE parameter 6.4 6-3 
distributed print/transfer options, to aux 
data devices Table 6-2 6-13 
processing. processing remote transactions 7.6 7-9 
RESFMT parameter 6.4 6-2 
Report address option, cassette/ sample use 47 4-20 
diskette, continuous output 5.12 5-42 screen format file 7.6 7-9 
screen formatted messages, 
Return function processing 6.6 6-5 
continuous output 5.7 5-16 screen with no variable data 6.9 6-10 
last output message 5.3 5-7 Fig. 6-7 6-12 
sending formatted screens to 
Rollback, specifying 2.6 2-14 aux-device 6.11 6-12 
SFS-options field, OMA 2.12 2-32 
Routing SFS_ parameter 6.4 6-2 
action program 7.2 7-3 storing formats for later 6.3 6-1 
directory 7.2 7-3 
operator 7.2 7-3 
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© Term Reference Page Term Reference Page 
Screen format services (cont) 
variable output data 6.6 6-5 Snap See dump. 
6.8 6-9 
6.9 6-10 Source-term-attributes 26 2-18 
work area required 47 4-20 
6.4 6-2 Source-term-msg-line-length 2.6 2-18 
Screen formatted messages See Source-term-msg-number-lines 2.6 2-18 
screen 
format Source terminal, specitying 
Services. characteristics 2.6 2-18 
Search and position option, cassette/ Source-terminal-id, IMA header 
diskette 5.12 5-42 description 2.9 2-25 
; use for processing remote 
Search and read option, cassette/ transaction 73 7-5 
diskette 5.12 5-41 
Source-terminal-type 2.6 2-18 
Search and read transparent, cassette/ 
diskette 9.12 5-41 Space suppression 5.6 5-12 
Secondary IMS 71 1-2 Standard-msg-line-length 2.6 2-16 
SEND function Standard-msg-number-lines 2.6 2-17 
configuration requirement 5.3 5-8 
continuous output program 5.7 9-15 Start-up, IMS, screen format 
description and status codes 5.18 5-49 requirements 65 6-3 
message switching 5.17 5-48 
multiple output messages 5.3 5-6 Status codes 
output-for-input queueing 5.14 5-44 invalid request 26 9-9 
restrictions, use for remote {IMS 7.3 7-6 1/0 error 26 9-10 
status codes 5.18 5-49 location in snap dumps 9.5 9-8 
Table 5-8 5-50 output delivery notice Table 5-4 5-19 
successful 9.18 5-49 SEND function 5.18 5-49 
; values and interpretation 2.6 2-9 
SEP specification, edit table generator B.3 B-5 Table C-l C-2 
Separator character, edit table Subroutines, internal 45 4-17 
generator B.3 B-5 
Success-unit-id 2.6 2-17 
Serially reusable code 
resetting fields 15 1-9 Succession, types 14 1-5 
turning off indicators and switches 15 1-9 
Successor-id 
SFS-location, OMA header 2.12 2-32 locating in snap dump 9.5 9-8 
processing errors 2.6 2-11 
SFS-options field, OMA 2.12 2-32 updating 28 2-23 
use 2.6 2-17 
SFS-type, OMA header 2.12 2-32 with termination indicators Table 2-5 2-13 
Simple transaction 1.3 1-3 Successor program 
continuous output 5.7 5-1 
Single-thread, snap dump 9.9 9-13 IMS delivery code 5.8 5-1 
® See also thread control block. naming 26 - 
7 using saved data 2.11 


See also successor-id. 
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Switching messages Termination indicator 
configuring disk queueing 5.17 5-48 default 2.6 2-11 
description 5.17 5-47 involuntary 2.6 2-13 
output only screens required 6.6 6-6 locating in snap dump 9.5 9-9 
SEND function 5.18 5-49 termination types and successor-id Table 2-5 = 2-13 
status codes for SEND function 5.18 5-49 updating 2.8 2-23 
Table 5-8 5-50 values and interpretations Table 2-4 2-12 
SWTCH transaction code 5.17 5-47 See also termination. 
to console 5.17 5-47 
Fig. 5-13 5-48 Terms, IMS 1.3 1-3 
SWITCH action program 5.17 5-47 Text-length field, OMA 
description 2.12 2-32 
Symbol table, for debugging Fig. 9-8 9-28 effect of incorrect length 2.14 2-36 
field in IMA header 2.9 2-26 
System console 5.20 5-54 field in OMA header 2.12 2-32 
moving value 2.14 2-37 
reading 2.14 2-35 
when zero 2.14 2-37 
Thread control block (THCB) 
multithread format Fig. 9-5 9-18 
T relationship to interface areas Fig. 9-2 9-4 
single-thread format Fig. 9-4 9-14 
Terminal control table, single and use, snap dump 9.8 9-10 
multithread format Fig. 9-6 9-20 
Transaction code 
Terminal printer (TP) definition 1.3 1-3 
continuous output 55 5-9 initiates transaction 3.3 3-2 
receiving DICE codes Table A-l A-6 Fig, 3-1 3-2 
invalid, entered on input screen 6.7 6-6 
Terminals smaller or larger than five 
continuous output 55 5-9 characters, edit table generator B.3 B-7 
displaying screen formats 6.6 6-5 
entering input messages for edit Transaction-id 2.6 2-16 
table generation B.6 B-15 
identifying local, for remote Transactions 
transactions 76 7-10 abnormal termination, message 
screen bypass 5.16 5-46 switching 5.13 5-44 
supporting DICE codes AS5 A-10 codes 13 1-4 
combined structures 1.4 1-8 
Termination completion 14 1-5 
abnormal Table 2-4 2-12 dialog 13 1-4 
allowable for program-initiated ending 3.13 3-17 
remote transactions 75 7-8 external succession example 3.4 3-2 
continuous output 5.7 5-13 function 3.5 3-3 
definition 14 1-5 initiating at another terminal 5.13 5-44 
delayed internal succession 14 1-7 identification 2.6 2-16 
external succession 14 1-6 initiation 3.3 3-2 
immediate internal succession 14 1-8 local 71 1 
IMS 3.14 3-19 operator-initiated 7.2 7-3 
indicator to obtain dump 2.6 2-13 74 7-7 
involuntary 26 2-13 program-initiated 7.2 7-4 
normal 14 1-6 75 7-8 
specifying type 2.6 2-11 remote 7 7-1 
7.2 7-3 
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Transactions (cont) 
sample processing 3.5 3-3 User files 
Fig. 3-2 3-5 describing 23 2-3 
simple 1.3 1-3 types 2.3 2-3 
structure 43 4-2 updating 2.3 2-4 
1.4 1-5 
Transfer all (ESC G) 5.6 5-11 
Table 5-2 5-10 
Transfer changed (ESC E) 5.6 5-11 
Table 5-2 5-10 
Transfer variable (ESC F) 5.6 5-11 
Table 5-2 5-10 V 
TYP specification, edit table generator B.3 B-9 Variable data 
moved to screen buffer 6.6 6-5 
moved to work area 6.6 6-5 
receiving order 6.8 6-9 
screen with no variable data 6.10 6-11 
Table 6-1 = 6-11 
U Voluntary abnormal termination 
with snap dump Table 2-4 = 2-12 
€& UNISCOPE 100 display terminal, without snap dump Table 2-4 2-12 
printing continuous output 5.6 5-12 
UNSOL parameter, IMS configuration 
multiple output messages 5.3 5-8 
output-for-input-queueing 5.13 5-44 ; 
Unsolicited output 
multiple output messages 5.3 5-8 
output-for-input queueing 5.13 5-44 W 
Update demand file 
continuity data area (CDA) 2.16 2-40 Work ae 4-20 
defining record length 28 2-23 configuring A] G 
device name 28 2-23 screen format services 47 4-20 
file description form coding 28 2-23 ; 
input message area (IMA) 2.11 2-28 Work-area-increment 26 2-17 
output form coding 2.8 2-24 P 2-17 
output message area (OMA) Fig. 2-10 2-35 Work-area-length 2. 2 
READ operation 2.8 2-24 
updating, PIB 2.8 2-23 
updating successor-id 2.8 2-23 
updating termination-indicator 2.8 2-23 
Updating 
continuity data area (CDA) 44 4-16 
program information block 2.8 2-23 
successor-id 2.8 2-23 Z 
@ termination indicator 2.8 2-23 
user files 2.3 2-4 ; 
7ZPCH command, use after recompile 8.5 8-8 


UPST byte values, edit table generator B.4 B-11 
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